feat: documenting types

yUnreal · May 21, 2024 · b1d9bba · b1d9bba
1 parent 93d72dd
commit b1d9bba
Show file tree

Hide file tree

Showing 3 changed files with 142 additions and 1 deletion.
diff --git a/src/typings/model.ts b/src/typings/model.ts
@@ -3,17 +3,47 @@ import { Schema } from '../structs/Schema';
 import { Infer } from './schema';
 import { AnyObject } from './utils';
 
+/**
+ * Options used when creating a new model
+ */
 export interface ModelOptions<S extends Schema<AnyObject>> {
+    /**
+     * The name of the model, must be unique
+     */
     name: string;
+    /**
+     * The schema to validate any data
+     */
     schema: S;
+    /**
+     * The global cache options for this model
+     */
     cache?: CacheOptions;
+    /**
+     * Whether the model is strict or not
+     */
     strict?: true;
+    /**
+     * The driver of the schema
+     */
     driver?: AnyDriver<S>;
 }
 
+/**
+ * Options that can be used for global model cache
+ */
 export interface CacheOptions {
+    /**
+     * The limit of documents to store in the cache
+     */
     limit?: number;
+    /**
+     * The lifetime of each document
+     */
     lifetime: number;
 }
 
+/**
+ * Any primitive driver
+ */
 export type AnyDriver<S extends Schema<AnyObject>> = JSONBasedDriver<Infer<S>>;
diff --git a/src/typings/query.ts b/src/typings/query.ts
@@ -1,6 +1,9 @@
 import { InferType, SchemaTypes } from './schema';
 import { DeepPartial, PartialRecord } from './utils';
 
+/**
+ * Options used when querying document(s)
+ */
 export interface QueryOptions<
     T extends Record<string, unknown>,
     K extends keyof T = keyof T,
@@ -24,6 +27,9 @@ export interface QueryOptions<
     skip?: number;
 }
 
+/**
+ * Options used when deleting a document
+ */
 export interface DeleteOneOptions<T extends Record<string, unknown>>
     extends QueryOptions<T> {
     /**
@@ -32,17 +38,35 @@ export interface DeleteOneOptions<T extends Record<string, unknown>>
     throw?: true;
 }
 
+/**
+ * Options used when updating a document
+ */
 export interface UpdateOneOptions<T extends Record<string, unknown>> {
+    /**
+     * The keys to set/update the value
+     */
     Set?: DeepPartial<T>;
+    /**
+     * The keys to remove/delete
+     */
     Remove?: (keyof T)[];
 }
 
+/**
+ * Utility type for projecting document(s)
+ */
 export type Projection<T extends Record<string, unknown>> =
     | {
+          /**
+           * Whether the key must be selected or not
+           */
           [K in keyof T]?: boolean;
       }
     | (keyof T)[];
 
+/**
+ * All query operators
+ */
 export enum Operators {
     // Any
     Equal = 'Equal',
@@ -65,6 +89,9 @@ export enum Operators {
 
     // Map
     Size = 'Size',
+
+    // RegExp
+    Matches = 'Matches',
 }
 
 export interface BaseQuery {
@@ -105,6 +132,10 @@ export interface MapBasedQuery extends BaseQuery {
 
 export type BooleanBasedQuery = BaseQuery;
 
+export interface RegExpBasedQuery extends BaseQuery {
+    [Operators.Matches]?: string;
+}
+
 export interface MappedQuery {
     [SchemaTypes.Number]: NumberBasedQuery;
     [SchemaTypes.String]: StringBasedQuery;
@@ -114,8 +145,16 @@ export interface MappedQuery {
     [SchemaTypes.Date]: DateBasedQuery;
     [SchemaTypes.Map]: MapBasedQuery;
     [SchemaTypes.Object]: Record<string, BaseQuery>;
+    [SchemaTypes.UUID]: BaseQuery;
+    [SchemaTypes.RegExp]: RegExpBasedQuery;
 }
 
+/**
+ * All available objetct queries
+ */
 export type AnyQuery = MappedQuery[SchemaTypes];
 
+/**
+ * Infer the query
+ */
 export type InferQuery<T> = MappedQuery[InferType<T>];
diff --git a/src/typings/schema.ts b/src/typings/schema.ts
@@ -11,6 +11,9 @@ import { StringSchemaKey } from '../structs/schema/StringSchemaKey';
 import { UUIDSchemaKey } from '../structs/schema/UUIDSchemaKey';
 import { AnyObject, UUID } from './utils';
 
+/**
+ * Types availables when creating a new schema key
+ */
 export enum SchemaTypes {
     String = 1,
     Number,
@@ -21,7 +24,6 @@ export enum SchemaTypes {
     BigInt,
     Date,
     Map,
-    Json,
     RegExp,
     UUID,
 }
@@ -49,18 +51,66 @@ export interface MappedSchemaTypes {
     [SchemaTypes.UUID]: UUID;
 }
 
+/**
+ * Options when creating a schema key
+ */
 export interface SchemaKeyOptions<Type extends SchemaTypes> {
+    /**
+     * The type of the schema key
+     */
     type: Type;
+    /**
+     * Whether this schema is optional or not
+     */
     optional?: true;
+    /**
+     * The default function for a default data
+     */
     default?(): MappedSchemaTypes[Type];
+    /**
+     * Whether the schema is nullable or not
+     */
     nullable?: true;
+    /**
+     * The cast function when validating a schema key
+     *
+     * @example
+     * type User = {
+     *    username: string;
+     * }
+     *
+     * const username = Schema.string().cast(String);
+     * const userSchema = new Schema<User>({
+     *    username,
+     * });
+     *
+     * // Works fine, `10` will be casted to String(10)
+     * userSchema.parse(10);
+     */
     cast?(value: unknown): MappedSchemaTypes[Type];
 }
 
+/**
+ * Options that can be used when creating a new schema
+ */
 export interface SchemaOptions {
+    /**
+     * Whether the schema is strict or not
+     */
     strict?: boolean;
 }
 
+/**
+ * Infer the schema object based in any POJO (Plain Old JavaScript Object)
+ *
+ * type User = {
+ *    username: string;
+ *    age: number;
+ * }
+ *
+ * // { username: StringSchemaKey; age: NumberSchemaKey; }
+ * type T1 = InferSchema<User>;
+ */
 export type InferSchema<S extends AnyObject> = {
     [K in keyof S]: InferType<S[K]> extends SchemaTypes.Array
         ? ArraySchemaKey<MappedSchemaKeys[InferType<S[K][number]>]>
@@ -88,6 +138,9 @@ export interface MappedSchemaKeys {
 
 export type ObjectShape = Record<string, AnySchemaKey>;
 
+/**
+ * All schemas key available
+ */
 export type AnySchemaKey =
     | BooleanSchemaKey
     | NumberSchemaKey
@@ -100,6 +153,9 @@ export type AnySchemaKey =
     | RegexSchemaKey
     | UUIDSchemaKey;
 
+/**
+ * Infer the type of a value based in itself
+ */
 export type InferType<S> = S extends MappedSchemaTypes[SchemaTypes]
     ? S extends RegExp
         ? SchemaTypes.RegExp
@@ -124,11 +180,27 @@ export type InferType<S> = S extends MappedSchemaTypes[SchemaTypes]
                           : never
     : never;
 
+/**
+ * Infer the raw type of a schema
+ *
+ * // { username: string; age: number; }
+ * type T1 = Infer<typeof userSchema>;
+ */
 export type Infer<S extends Schema<AnyObject>> = S extends Schema<infer T>
     ? T
     : never;
 
+/**
+ * Options used when creating a new effect in a schema key
+ */
 export interface SchemaKeyEffect<Type extends SchemaTypes> {
+    /**
+     * The function used to validate the effect
+     * @param value The value to use
+     */
     effect: (value: MappedSchemaTypes[Type]) => boolean;
+    /**
+     * The error message when the effect is not successfull
+     */
     message?: string;
 }