vortez 5.0.0-dev.18 → 5.0.0

package/build/utilities/Utilities.js

@@ -1,120 +1,99 @@
 /**
  * @author NetFeez <netfeez.dev@gmail.com>
- * @description add useful functions to the Vortez.
+ * @description Exports all utility classes and functions, providing a centralized access point for various helper methods used throughout the project.
+ * This includes:
+ * - file operations: `Utilities.File`.
+ * - object manipulation: `Utilities.Object`.
+ * - encoding: `Utilities.Encoding`.
+ * - time utilities: `Utilities.Time`.
+ * and more utilities.
  * @license Apache-2.0
  */
-import { promises as FSP } from "fs";
 import _Path from './Path.js';
 import _Env from './Env.js';
 import _ConsoleUI from './ConsoleUI.js';
 import _DebugUI from './DebugUI.js';
+import _Schema from './schema/Schema.js';
+import _Flatten from './Flatten.js';
+import _File from './File.js';
+import _Object from './Object.js';
+import _Encoding from './Encoding.js';
+import _Time from './Time.js';
 export { Path } from './Path.js';
 export { Env } from './Env.js';
 export { ConsoleUI } from './ConsoleUI.js';
 export { DebugUI } from './DebugUI.js';
+export { Schema } from './schema/Schema.js';
+export { Flatten } from './Flatten.js';
+export { File } from './File.js';
+export { Object } from './Object.js';
+export { Encoding } from './Encoding.js';
+export { Time } from './Time.js';
 export class Utilities {
     /**
-     * Checks if a file exists asynchronously.
-     * @param path - The path to the file.
-     * @returns A promise that resolves to `true` if the file exists, `false` otherwise.
+     * Checks if a file exists at the given path.
+     * @param path - The file path to check.
+     * @returns A promise that resolves to true if the file exists, false otherwise.
+     * @deprecated Use Utilities.File.exists instead.
      */
     static async fileExists(path) {
-        return FSP.access(path).then(() => true).catch(() => false);
+        return Utilities.File.exists(path);
     }
     /**
-     * Compares two objects recursively for deep equality.
-     * @param obj1 - The first object to compare.
-     * @param obj2 - The second object to compare.
-     * @returns A boolean indicating whether the objects are deeply equal or not.
+     * Checks if two values are deeply equal.
+     * @param obj1 - The first value to compare.
+     * @param obj2 - The second value to compare.
+     * @returns A boolean indicating if the values are deeply equal.
+     * @deprecated Use Utilities.Object.deepEqual instead.
      */
     static deepEqual(obj1, obj2) {
-        if (obj1 === obj2)
-            return true;
-        if (typeof obj1 !== typeof obj2 ||
-            obj1 === null || obj2 === null)
-            return false;
-        const keys1 = Object.keys(obj1);
-        const keys2 = Object.keys(obj2);
-        if (keys1.length !== keys2.length)
-            return false;
-        for (const key of keys1)
-            if (!keys2.includes(key) ||
-                !this.deepEqual(obj1[key], obj2[key]))
-                return false;
-        return true;
+        return Utilities.Object.deepEqual(obj1, obj2);
     }
     /**
-     * Flattens a nested object into a single-level object with dot notation keys.
+     * Flattens a nested object into a single-level object with dot-separated keys.
      * @param object - The object to flatten.
-     * @param depth - The maximum depth to which the object should be flattened.
-     * @returns The flattened object.
+     * @param depth - The maximum depth to flatten (default is 10).
+     * @returns A new object with flattened keys.
+     * @deprecated Use Utilities.Flatten.object instead.
      */
     static flattenObject(object, depth = 10) {
-        return this.flattenCore(object, depth);
-    }
-    static flattenCore(object, depth = 10, prefix = '') {
-        const result = {};
-        for (const key in object) {
-            const newKey = prefix ? `${prefix}.${key}` : key;
-            const value = object[key];
-            if (typeof value === 'object' && !Array.isArray(value) && value !== null && depth > 0) {
-                Object.assign(result, Utilities.flattenCore(value, depth - 1, newKey));
-            }
-            else {
-                result[newKey] = value;
-            }
-        }
-        return result;
+        return Utilities.Flatten.object(object, depth);
     }
     /**
-     * Reconstructs a nested object from a flattened object with dot notation keys.
-     * @template Result - The type of the unflattened object.
-     * @param obj - The flattened object to un flatten.
-     * @returns The unflattened object.
+     * Unflattens a flattened object back into its original nested structure.
+     * @param obj - The flattened object to unflatten.
+     * @returns A new object with the original nested structure.
+     * @deprecated Use Utilities.Flatten.unObject instead.
      */
     static unFlattenObject(obj) {
-        const result = {};
-        for (const key in obj) {
-            const value = obj[key];
-            const [first, ...rest] = key.split('.');
-            if (rest.length === 0)
-                result[first] = value;
-            else {
-                const last = rest.pop();
-                const subObj = result[first] ?? {};
-                let current = subObj;
-                rest.forEach((k) => {
-                    current = current[k] ?? (current[k] = {});
-                });
-                current[last] = value;
-                result[first] = subObj;
-            }
-        }
-        return result;
+        return Utilities.Flatten.unObject(obj);
     }
     /**
-     * Pauses the execution of the program for a specified duration.
+     * Pauses execution for a specified duration.
      * @param ms - The number of milliseconds to sleep.
      * @returns A promise that resolves after the given time.
+     * @deprecated Use Utilities.Time.sleep instead.
      */
     static sleep(ms) {
-        return new Promise(resolve => setTimeout(resolve, ms));
+        return Utilities.Time.sleep(ms);
     }
     /**
      * Encodes a string to base64url format.
-     * @param data - The string that needs to be encoded.
+     * @param data - The string to encode.
      * @returns The base64url-encoded string.
+     * @deprecated Use Utilities.Encoding.base64UrlEncode instead.
      */
     static base64UrlEncode(data) {
-        return Buffer.from(data).toString('base64url');
+        return Utilities.Encoding.base64UrlEncode(data);
     }
     /**
      * Decodes a base64url-encoded string.
-     * @param data - The base64url-encoded string that needs to be decoded.
-     * @returns The decoded string.
+     * @param data - The base64url-encoded string to decode.
+     * @returns The decoded UTF-8 string.
+     * @deprecated Use Utilities.Encoding.base64UrlDecode instead.
      */
     static base64UrlDecode(data) {
-        return Buffer.from(data, 'base64url').toString('utf8');
+        return Utilities.Encoding.base64UrlDecode(data);
     }
 }
 (function (Utilities) {
@@ -122,6 +101,12 @@ export class Utilities {
     Utilities.Env = _Env;
     Utilities.ConsoleUI = _ConsoleUI;
     Utilities.DebugUI = _DebugUI;
+    Utilities.Schema = _Schema;
+    Utilities.Flatten = _Flatten;
+    Utilities.File = _File;
+    Utilities.Object = _Object;
+    Utilities.Encoding = _Encoding;
+    Utilities.Time = _Time;
 })(Utilities || (Utilities = {}));
 export default Utilities;
 //# sourceMappingURL=Utilities.js.map

package/build/utilities/Utilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"Utilities.js","sourceRoot":"","sources":["../../src/utilities/Utilities.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Utilities.js","sourceRoot":"","sources":["../../src/utilities/Utilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,MAAM,WAAW,CAAC;AAC9B,OAAO,IAAI,MAAM,UAAU,CAAC;AAC5B,OAAO,UAAU,MAAM,gBAAgB,CAAC;AACxC,OAAO,QAAQ,MAAM,cAAc,CAAC;AACpC,OAAO,OAAO,MAAM,oBAAoB,CAAC;AACzC,OAAO,QAAQ,MAAM,cAAc,CAAC;AACpC,OAAO,KAAK,MAAM,WAAW,CAAC;AAC9B,OAAO,OAAO,MAAM,aAAa,CAAC;AAClC,OAAO,SAAS,MAAM,eAAe,CAAC;AACtC,OAAO,KAAK,MAAM,WAAW,CAAC;AAE9B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,OAAO,SAAS;IAClB;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAY;QACvC,OAAO,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IACD;;;;;;OAMG;IACI,MAAM,CAAC,SAAS,CAAC,IAAS,EAAE,IAAS;QACxC,OAAO,SAAS,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAClD,CAAC;IACD;;;;;;OAMG;IACI,MAAM,CAAC,aAAa,CAA0C,MAAS,EAAE,QAAW,EAAO;QAC9F,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,MAAkC,EAAE,KAAK,CAAmC,CAAC;IACjH,CAAC;IACD;;;;;OAKG;IACI,MAAM,CAAC,eAAe,CAA2B,GAAQ;QAC5D,OAAO,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAS,GAAiC,CAAC,CAAC;IACjF,CAAC;IACD;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAC,EAAU;QAC1B,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACpC,CAAC;IACD;;;;;OAKG;IACI,MAAM,CAAC,eAAe,CAAC,IAAY;QACtC,OAAO,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;IACD;;;;;OAKG;IACI,MAAM,CAAC,eAAe,CAAC,IAAY;QACtC,OAAO,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;IACpD,CAAC;CACJ;AACD,WAAiB,SAAS;IACR,cAAI,GAAG,KAAK,CAAC;IACb,aAAG,GAAG,IAAI,CAAC;IACX,mBAAS,GAAG,UAAU,CAAC;IACvB,iBAAO,GAAG,QAAQ,CAAC;IACnB,gBAAM,GAAG,OAAO,CAAC;IACjB,iBAAO,GAAG,QAAQ,CAAC;IACnB,cAAI,GAAG,KAAK,CAAC;IACb,gBAAM,GAAG,OAAO,CAAC;IACjB,kBAAQ,GAAG,SAAS,CAAC;IACrB,cAAI,GAAG,KAAK,CAAC;AA0C/B,CAAC,EApDgB,SAAS,KAAT,SAAS,QAoDzB;AACD,eAAe,SAAS,CAAC"}

package/build/utilities/schema/Introspection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Provides utilities for schema introspection, including listing unique properties and converting custom schemas to JSON Schema format.
+ * @license Apache-2.0
+ */
+import type { JSONSchema } from './JSONSchema.js';
+import type { Schema } from './Schema.js';
+export declare class Introspection {
+    /**
+     * Lists all unique properties in a schema, including nested unique properties, and returns their full paths.
+     * @param doc The schema to list unique properties from
+     * @param parentKey The parent key of the current schema, used for building full paths of nested properties
+     * @returns An array of full paths to unique properties in the schema
+     */
+    static listUniques(doc: Schema.Schema, parentKey?: string): string[];
+    /**
+     * Converts a schema to a JSON Schema, used for validating data against the schema and generating documentation.
+     * @param schema The schema to convert to JSON Schema
+     * @returns The JSON Schema representation of the input schema
+     */
+    static toJsonSchema(schema: Schema.Schema): JSONSchema.schema;
+}
+export declare namespace Introspection { }
+export default Introspection;

package/build/utilities/schema/Introspection.js

@@ -0,0 +1,87 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Provides utilities for schema introspection, including listing unique properties and converting custom schemas to JSON Schema format.
+ * @license Apache-2.0
+ */
+export class Introspection {
+    /**
+     * Lists all unique properties in a schema, including nested unique properties, and returns their full paths.
+     * @param doc The schema to list unique properties from
+     * @param parentKey The parent key of the current schema, used for building full paths of nested properties
+     * @returns An array of full paths to unique properties in the schema
+     */
+    static listUniques(doc, parentKey) {
+        const uniques = [];
+        for (const key in doc) {
+            const prop = doc[key];
+            if (key !== '_id' && prop.unique)
+                uniques.push(parentKey ? `${parentKey}.${key}` : key);
+            if (prop.type === 'object') {
+                uniques.push(...this.listUniques(prop.schema, parentKey ? `${parentKey}.${key}` : key));
+            }
+        }
+        return uniques;
+    }
+    /**
+     * Converts a schema to a JSON Schema, used for validating data against the schema and generating documentation.
+     * @param schema The schema to convert to JSON Schema
+     * @returns The JSON Schema representation of the input schema
+     */
+    static toJsonSchema(schema) {
+        const sch = {};
+        sch.type = 'object';
+        sch.properties = {};
+        for (const key in schema) {
+            const prop = schema[key];
+            let subSch = {};
+            subSch.type = prop.nullable ? [prop.type, 'null'] : prop.type;
+            if (prop.required) {
+                if (sch.required == null)
+                    sch.required = [];
+                sch.required.push(key);
+            }
+            switch (prop.type) {
+                case 'string': {
+                    if (prop.enum !== undefined)
+                        subSch.enum = [...prop.enum];
+                    if (prop.minLength !== undefined)
+                        subSch.minLength = prop.minLength;
+                    if (prop.maxLength !== undefined)
+                        subSch.maxLength = prop.maxLength;
+                    if (prop.pattern !== undefined)
+                        subSch.pattern = prop.pattern.source;
+                    break;
+                }
+                case 'boolean': break;
+                case 'number': {
+                    if (prop.minimum !== undefined)
+                        subSch.minimum = prop.minimum;
+                    if (prop.maximum !== undefined)
+                        subSch.maximum = prop.maximum;
+                    break;
+                }
+                case 'array': {
+                    if (prop.minimum !== undefined)
+                        subSch.minItems = prop.minimum;
+                    if (prop.maximum !== undefined)
+                        subSch.maxItems = prop.maximum;
+                    const itemContainer = this.toJsonSchema({ item: prop.property });
+                    const itemSchema = itemContainer.properties?.item;
+                    if (itemSchema)
+                        subSch.items = itemSchema;
+                    break;
+                }
+                case 'object': {
+                    subSch = this.toJsonSchema(prop.schema);
+                    if (prop.nullable)
+                        subSch.type = ['object', 'null'];
+                    break;
+                }
+            }
+            sch.properties[key] = subSch;
+        }
+        return sch;
+    }
+}
+export default Introspection;
+//# sourceMappingURL=Introspection.js.map

package/build/utilities/schema/Introspection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Introspection.js","sourceRoot":"","sources":["../../../src/utilities/schema/Introspection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,OAAO,aAAa;IACtB;;;;;OAKG;IACI,MAAM,CAAC,WAAW,CAAC,GAAkB,EAAE,SAAkB;QAC5D,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;YACpB,MAAM,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACtB,IAAI,GAAG,KAAK,KAAK,IAAI,IAAI,CAAC,MAAM;gBAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YACxF,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACzB,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC5F,CAAC;QACL,CAAC;QACD,OAAO,OAAO,CAAC;IACnB,CAAC;IACD;;;;OAIG;IACI,MAAM,CAAC,YAAY,CAAC,MAAqB;QAC5C,MAAM,GAAG,GAAsB,EAAE,CAAC;QAClC,GAAG,CAAC,IAAI,GAAG,QAAQ,CAAC;QACpB,GAAG,CAAC,UAAU,GAAG,EAAE,CAAC;QACpB,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YACvB,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,IAAI,MAAM,GAAsB,EAAE,CAAC;YACnC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAC9D,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAChB,IAAI,GAAG,CAAC,QAAQ,IAAI,IAAI;oBAAE,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;gBAC5C,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;YACD,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;gBAChB,KAAK,QAAQ,CAAC,CAAC,CAAC;oBACZ,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;wBAAE,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;oBAC1D,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;wBAAE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;oBACpE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;wBAAE,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;oBACpE,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;wBAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;oBACrE,MAAM;gBACV,CAAC;gBACD,KAAK,SAAS,CAAC,CAAC,MAAM;gBACtB,KAAK,QAAQ,CAAC,CAAC,CAAC;oBACZ,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;wBAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;oBAC9D,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;wBAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;oBAC9D,MAAM;gBACV,CAAC;gBACD,KAAK,OAAO,CAAC,CAAC,CAAC;oBACX,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;wBAAE,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC;oBAC/D,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;wBAAE,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC;oBAE/D,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;oBACjE,MAAM,UAAU,GAAG,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC;oBAClD,IAAI,UAAU;wBAAE,MAAM,CAAC,KAAK,GAAG,UAAU,CAAC;oBAC1C,MAAM;gBACV,CAAC;gBACD,KAAK,QAAQ,CAAC,CAAC,CAAC;oBACZ,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;oBACxC,IAAI,IAAI,CAAC,QAAQ;wBAAE,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;oBACpD,MAAM;gBACV,CAAC;YACL,CAAC;YACD,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;QACjC,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;CACJ;AAED,eAAe,aAAa,CAAC"}

package/build/utilities/schema/JSONSchema.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Provides type definitions for JSON Schema, a powerful tool for validating and describing the structure of JSON data.
+ * @license Apache-2.0
+ */
+export declare namespace JSONSchema {
+    type schemeArray = schemeTypes[];
+    type schemaObject = {
+        [key: string]: schemeTypes;
+    };
+    interface SchemaTypeMap {
+        string: string;
+        number: number;
+        boolean: boolean;
+        object: schemaObject;
+        array: schemeArray;
+        null: null;
+    }
+    type schemaNames = keyof SchemaTypeMap;
+    type schemeTypes = SchemaTypeMap[schemaNames];
+    type schemaVersion = string;
+    type schema = {
+        title?: string;
+        description?: string;
+        multipleOf?: number;
+        maximum?: number;
+        exclusiveMaximum?: boolean;
+        minimum?: number;
+        exclusiveMinimum?: boolean;
+        maxLength?: number;
+        minLength?: number;
+        pattern?: string;
+        additionalItems?: schema;
+        items?: schema | schema[];
+        maxItems?: number;
+        minItems?: number;
+        uniqueItems?: boolean;
+        maxProperties?: number;
+        minProperties?: number;
+        required?: string[];
+        properties?: {
+            [key: string]: schema;
+        };
+        additionalProperties?: boolean | schema;
+        patternProperties?: {
+            [key: string]: schema;
+        };
+        dependencies?: {
+            [key: string]: string[] | schema;
+        };
+        enum?: schemeTypes[];
+        type?: schemaNames | schemaNames[];
+        allOf?: schema[];
+        anyOf?: schema[];
+        oneOf?: schema[];
+        not?: schema;
+        extends?: string | string[];
+    };
+}
+/**
+ * provide the type definition of a json schema
+ * @param schema the json schema to validate
+ */
+export declare function schema(schema: JSONSchema.schema): JSONSchema.schema;
+export declare const JSONSchema: {
+    schema: typeof schema;
+};
+export default JSONSchema;

package/build/utilities/schema/JSONSchema.js

@@ -0,0 +1,13 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Provides type definitions for JSON Schema, a powerful tool for validating and describing the structure of JSON data.
+ * @license Apache-2.0
+ */
+/**
+ * provide the type definition of a json schema
+ * @param schema the json schema to validate
+ */
+export function schema(schema) { return schema; }
+export const JSONSchema = { schema };
+export default JSONSchema;
+//# sourceMappingURL=JSONSchema.js.map

package/build/utilities/schema/JSONSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JSONSchema.js","sourceRoot":"","sources":["../../../src/utilities/schema/JSONSchema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoEH;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,MAAyB,IAAI,OAAO,MAAM,CAAC,CAAC,CAAC;AACpE,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,MAAM,EAAE,CAAC;AACrC,eAAe,UAAU,CAAC"}

package/build/utilities/schema/Schema.d.ts

@@ -0,0 +1,253 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Provides a comprehensive schema validation and processing system, allowing developers to define complex data structures.
+ * @license Apache-2.0
+ */
+import type Utilities from '../Utilities.js';
+import _SchemaError from './SchemaError.js';
+import _JSONSchema from './JSONSchema.js';
+import _Introspection from './Introspection.js';
+import _Validator from './Validator.js';
+export { SchemaError } from './SchemaError.js';
+export { JSONSchema } from './JSONSchema.js';
+export { Introspection } from './Introspection.js';
+export { Validator } from './Validator.js';
+export declare class Schema<const S extends Schema.Schema> {
+    readonly schema: S;
+    constructor(schema: S);
+    /**
+     * Get the inferred type of the schema.
+     *
+     * ⚠️ IMPORTANT: This getter returns an EMPTY object. It is designed ONLY for type inference.
+     *
+     * Usage: Use with `typeof` to extract the inferred type:
+     * ```typescript
+     * type infered = typeof schemaInstance.infer;
+     * ```
+     *
+     * DO NOT use the returned value at runtime - it's always an empty object.
+     * This is purely a TypeScript type utility.
+     *
+     * @returns An empty object with the inferred type
+     */
+    get infer(): Schema.Infer<this['schema']>;
+    /**
+     * Get the inferred type of the schema for processing (i.e., before applying defaults and handling optional properties).
+     *
+     * ⚠️ IMPORTANT: This getter returns an EMPTY object. It is designed ONLY for type inference.
+     *
+     * Usage: Use with `typeof` to extract the inferred type for processing:
+     * ```typescript
+     * type inferedToProcess = typeof schemaInstance.inferToProcess;
+     * ```
+     *
+     * DO NOT use the returned value at runtime - it's always an empty object.
+     * This is purely a TypeScript type utility.
+     */
+    get inferToProcess(): Schema.InferToProcess<this['schema']>;
+    /**
+     * get the json schema as an object
+     * @returns the json schema
+     */
+    get jsonSchema(): Schema.JSONSchema.schema;
+    /**
+     * get the json schema as a JSON string
+     * @returns the json schema as a string
+     */
+    get jsonSchemaJSON(): string;
+    /**
+     * get the list of unique keys
+     * @returns the list of unique keys
+     */
+    get uniques(): string[];
+    /**
+     * process the provided data
+     * @param data the data to process
+     * @param partial if the data is partial
+     * @returns the processed data
+     * @throws schemaError if the data is not valid
+     */
+    processData(data: Schema.Infer<this['schema']>, partial?: boolean): Schema.Infer<this['schema']>;
+    processData(data: Schema.InferToProcess<this['schema']>, partial?: boolean): Schema.Infer<this['schema']>;
+    /**
+     * process the provided data as partial, meaning that it will only validate the provided properties and ignore the rest.
+     * this is useful for validating data that is only meant to update a document, where only a subset of the properties are provided.
+     * @param data the data to process
+     * @returns the processed data
+     * @throws schemaError if the data is not valid
+     */
+    processPartialData(data: Partial<Schema.FlattenToProcess<this['schema']>> & Partial<Schema.InferToProcess<this['schema']>> & Schema.Document): Partial<Schema.Flatten<this['schema']>> & Partial<Schema.Infer<this['schema']>> & Schema.Document;
+    processPartialData(data: Partial<Schema.Flatten<this['schema']>> & Partial<Schema.Infer<this['schema']>> & Schema.Document): Partial<Schema.Flatten<this['schema']>> & Partial<Schema.Infer<this['schema']>> & Schema.Document;
+    /**
+     * process a property
+     * @param data the data to process
+     * @param prop the property to process
+     * @param key the key of the property
+     * @param partial if the data is partial
+     * @returns the processed data
+     * @throws schemaError if the data is not valid
+     */
+    protected processProperty(data: any, prop: Schema.property, key: string, partial?: boolean): any;
+    /**
+     * validate a array
+     * @param value the value to validate
+     * @param prop the property to validate
+     * @param key the key of the property
+     * @returns the data
+     * @throws schemaError if the data is not valid
+     */
+    protected processArray(value: any[], prop: Schema.Property.Array, key: string): any;
+    /**
+     * validate a object
+     * @param value the value to validate
+     * @param prop the property to validate
+     * @param key the key of the property
+     * @returns the data
+     * @throws schemaError if the data is not valid
+     */
+    protected processObject(value: any, prop: Schema.Property.Object, key: string, partial?: boolean): any;
+    /**
+     * validate a array
+     * @param value the value to validate
+     * @param prop the property to validate
+     * @param key the key of the property
+     * @throws schemaError if the data is not valid
+     */
+    protected validateArray(value: any, prop: Schema.Property.Array, key: string): void;
+    /**
+     * generate a list of unique keys
+     * @param doc the schema to validate
+     * @param parentKey the parent key of the schema
+     * @returns a list of unique keys
+    */
+    protected listUniques(doc?: Schema.Schema, parentKey?: string): string[];
+    /**
+     * convert a schema to a JSON schema
+     * @param schema the schema to convert
+     * @returns the JSON schema
+    */
+    protected toJsonSchema(schema?: Schema.Schema): Schema.JSONSchema.schema;
+    /**
+     * -- TYPE GUARD --
+     * verify if the key is in the schema
+     * @param doc the object to verify
+     * @param key the key to verify
+     * @returns true if the key is in the schema
+     */
+    private isKeyOf;
+}
+export declare namespace Schema {
+    export import SchemaError = _SchemaError;
+    export import JSONSchema = _JSONSchema;
+    export import Introspection = _Introspection;
+    export import Validator = _Validator;
+    type Infer<S extends Schema> = Schema.Infer.schema<S>;
+    type InferToProcess<S extends Schema> = Schema.Infer.schemaToProcess<S>;
+    type Flatten<S extends Schema.Schema> = (Utilities.Flatten.Object<Infer.schema<S>, 10>);
+    type FlattenToProcess<S extends Schema.Schema> = (Utilities.Flatten.Object<Infer.schemaToProcess<S>, 10>);
+    interface Document {
+        [Key: string]: any;
+    }
+    interface TypeMap {
+        string: string;
+        number: number;
+        boolean: boolean;
+        object: any;
+        array: any[];
+    }
+    namespace Helper {
+        type HasDefault<T> = T extends {
+            default: any;
+        } ? true : false;
+        type IsRequired<T> = T extends {
+            required: true;
+        } ? true : false;
+        type IsNullable<T> = T extends {
+            nullable: true;
+        } ? true : false;
+        type DefaultValue<T> = T extends {
+            default: infer D;
+        } ? D : never;
+        type Prettify<T> = {
+            [K in keyof T]: T[K];
+        } & {};
+    }
+    namespace Property {
+        interface Base<T extends keyof TypeMap> {
+            type: T;
+            required?: boolean;
+            nullable?: boolean;
+            unique?: boolean;
+            default?: TypeMap[T] | null;
+        }
+        export interface String extends Base<'string'> {
+            enum?: readonly string[];
+            pattern?: RegExp;
+            minLength?: number;
+            maxLength?: number;
+        }
+        export interface Number extends Base<'number'> {
+            minimum?: number;
+            maximum?: number;
+        }
+        export interface Boolean extends Base<'boolean'> {
+        }
+        export interface Object extends Base<'object'> {
+            schema: Schema;
+        }
+        export interface Array extends Base<'array'> {
+            property: property;
+            minimum?: number;
+            maximum?: number;
+        }
+        export interface Map {
+            string: String;
+            number: Number;
+            boolean: Boolean;
+            object: Object;
+            array: Array;
+        }
+        export {};
+    }
+    type property = Property.Map[keyof Property.Map];
+    interface Schema {
+        [Key: string]: property;
+    }
+    namespace Infer {
+        export type Mode = 'partial' | 'process' | 'complete';
+        type ObjectByMode<S extends Schema.Schema, M extends Mode> = (M extends 'process' ? schemaToProcess<S> : M extends 'partial' ? schemaPartial<S> : schema<S>);
+        export type propertyType<P extends Schema.property, M extends Mode = 'complete'> = (P extends Property.String ? P extends {
+            enum: readonly (infer E extends string)[];
+        } ? E : string : P extends Property.Number ? number : P extends Property.Boolean ? boolean : P extends Property.Object ? (ObjectByMode<P['schema'], M>) : P extends Property.Array ? propertyType<P['property'], M>[] : never);
+        type OptionalPropertyValue<P extends Schema.property, M extends Mode> = (Helper.IsNullable<P> extends true ? propertyType<P, M> | null : propertyType<P, M> | undefined);
+        type DefaultedPropertyValue<P extends Schema.property, M extends Mode> = (Helper.DefaultValue<P> extends null ? propertyType<P, M> | null : propertyType<P, M>);
+        type RequiredPropertyValue<P extends Schema.property, M extends Mode> = (Helper.IsNullable<P> extends true ? propertyType<P, M> | null : propertyType<P, M>);
+        export type property<P extends Schema.property, M extends Mode = 'complete'> = (Helper.HasDefault<P> extends true ? DefaultedPropertyValue<P, M> : Helper.IsRequired<P> extends true ? RequiredPropertyValue<P, M> : OptionalPropertyValue<P, M>);
+        type RequiredKeys<S extends Schema> = {
+            [K in keyof S]: Helper.IsRequired<S[K]> extends true ? K : Helper.HasDefault<S[K]> extends true ? K : never;
+        }[keyof S];
+        type OptionalKeys<S extends Schema> = Exclude<keyof S, RequiredKeys<S>>;
+        type RequiredToProcessKeys<S extends Schema> = {
+            [K in keyof S]: Helper.IsRequired<S[K]> extends true ? Helper.HasDefault<S[K]> extends false ? K : never : never;
+        }[keyof S];
+        type OptionalToProcessKeys<S extends Schema> = Exclude<keyof S, RequiredToProcessKeys<S>>;
+        export type schema<S extends Schema> = Helper.Prettify<{
+            [K in RequiredKeys<S>]: property<S[K]>;
+        } & {
+            [K in OptionalKeys<S>]?: property<S[K]>;
+        }>;
+        export type schemaToProcess<S extends Schema> = Helper.Prettify<{
+            [K in RequiredToProcessKeys<S>]: property<S[K], 'process'>;
+        } & {
+            [K in OptionalToProcessKeys<S>]?: property<S[K], 'process'>;
+        }>;
+        export type schemaPartial<S extends Schema> = Helper.Prettify<{
+            [K in keyof S]?: property<S[K], 'partial'>;
+        }>;
+        export type schemaBase<S extends Schema> = {
+            [K in keyof S]: property<S[K]>;
+        };
+        export {};
+    }
+}
+export default Schema;