@acodeninja/persist 3.0.0-next.12 → 3.0.0-next.13

package/src/Schema.js

@@ -0,0 +1,166 @@
+import Model from './data/Model.js';
+import ajv from 'ajv';
+import ajvErrors from 'ajv-errors';
+import ajvFormats from 'ajv-formats';
+
+/**
+ * A class responsible for compiling raw schema definitions into a format that can be validated using the AJV (Another JSON Validator) library.
+ */
+class Schema {
+    /**
+     * Compiles a raw schema into a validation-ready schema, and returns a class that extends `CompiledSchema`.
+     *
+     * This method converts a given schema into a JSON schema-like format, setting up properties, types, formats, and validation rules.
+     * It uses AJV for the validation process and integrates with model types and their specific validation rules.
+     *
+     * @param {Object|Model} rawSchema - The raw schema or model definition to be compiled.
+     * @returns {CompiledSchema} - A class that extends `CompiledSchema`, with the compiled schema and validator attached.
+     *
+     * @example
+     * const schemaClass = Schema.compile(MyModelSchema);
+     * const isValid = schemaClass.validate(data); // Throws ValidationError if data is invalid.
+     */
+    static compile(rawSchema) {
+        const validation = new ajv({allErrors: true});
+
+        ajvErrors(validation);
+        ajvFormats(validation);
+
+        function BuildSchema(schemaSegment) {
+            const thisSchema = {};
+
+            if (Model.isModel(schemaSegment)) {
+                thisSchema.required = ['id'];
+                thisSchema.type = 'object';
+                thisSchema.additionalProperties = false;
+                thisSchema.properties = {
+                    id: {
+                        type: 'string',
+                        pattern: `^${schemaSegment.toString()}/[A-Z0-9]+$`,
+                    },
+                };
+
+                for (const [name, type] of Object.entries(schemaSegment)) {
+                    if (['indexedProperties', 'searchProperties'].includes(name)) continue;
+
+                    const property = type instanceof Function && !type.prototype ? type() : type;
+
+                    if (property?._required || property?._items?._type?._required) {
+                        thisSchema.required.push(name);
+                    }
+
+                    if (Model.isModel(property)) {
+                        thisSchema.properties[name] = {
+                            type: 'object',
+                            additionalProperties: false,
+                            required: ['id'],
+                            properties: {
+                                id: {
+                                    type: 'string',
+                                    pattern: `^${property.toString()}/[A-Z0-9]+$`,
+                                },
+                            },
+                        };
+                        continue;
+                    }
+
+                    thisSchema.properties[name] = BuildSchema(property);
+                }
+
+                return thisSchema;
+            }
+
+            if (schemaSegment._schema) {
+                return schemaSegment._schema;
+            }
+
+            thisSchema.type = schemaSegment?._type;
+
+            if (schemaSegment?._format) {
+                thisSchema.format = schemaSegment._format;
+            }
+
+            if (schemaSegment?._items) {
+                thisSchema.items = {};
+                thisSchema.items.type = schemaSegment._items._type;
+                if (schemaSegment._items._format)
+                    thisSchema.items.format = schemaSegment._items._format;
+            }
+
+            return thisSchema;
+        }
+
+        const builtSchema = BuildSchema(rawSchema);
+
+        return new CompiledSchema(validation.compile(builtSchema));
+    }
+}
+
+
+/**
+ * Represents a compiled schema used for validating data models.
+ * This class provides a mechanism to validate data using a precompiled schema and a validator function.
+ */
+export class CompiledSchema {
+    /**
+     * The validator function used to validate data against the schema.
+     * @type {?Function}
+     * @private
+     */
+    #validator = null;
+
+    constructor(validator) {
+        this.#validator = validator;
+    }
+
+    /**
+     * Validates the given data against the compiled schema.
+     *
+     * If the data is an instance of a model, it will be converted to a plain object via `toData()` before validation.
+     *
+     * @param {Object|Model} data - The data or model instance to be validated.
+     * @returns {boolean} - Returns `true` if the data is valid according to the schema.
+     * @throws {ValidationError} - Throws a `ValidationError` if the data is invalid.
+     */
+    validate(data) {
+        let inputData = structuredClone(data);
+
+        if (Model.isModel(data)) {
+            inputData = data.toData();
+        }
+
+        const valid = this.#validator?.(inputData);
+
+        if (valid) return valid;
+
+        throw new ValidationError(inputData, this.#validator.errors);
+    }
+}
+
+/**
+ * Represents a validation error that occurs when a model or data fails validation.
+ * Extends the built-in JavaScript `Error` class.
+ */
+export class ValidationError extends Error {
+    /**
+     * Creates an instance of `ValidationError`.
+     *
+     * @param {Object} data - The data that failed validation.
+     * @param {Array<Object>} errors - A list of validation errors, each typically containing details about what failed.
+     */
+    constructor(data, errors) {
+        super('Validation failed');
+        /**
+         * An array of validation errors, containing details about each failed validation.
+         * @type {Array<Object>}
+         */
+        this.errors = errors;
+        /**
+         * The data that caused the validation error.
+         * @type {Object}
+         */
+        this.data = data;
+    }
+}
+
+export default Schema;

package/src/{Query.js → data/FindIndex.js}

@@ -26,37 +26,47 @@
  *   }
  * });
  */
-class Query {
+class FindIndex {
     /**
      * The query object that defines the search criteria.
      * @type {Object}
+     * @private
      */
-    query;
+    #index;
+
+    /**
+     * @type {Model.constructor} - The model class.
+     * @private
+     */
+    #modelConstructor;
 
     /**
      * Constructs a new `Query` instance with the provided query object.
      *
-     * @param {Object} query - The structured query object defining the search criteria.
+     * @param {Model.constructor} constructor - The model class.
+     * @param {Record<string, Model>} index - The index dataset to search through.
      */
-    constructor(query) {
-        this.query = query;
+    constructor(constructor, index) {
+        this.#index = index;
+        this.#modelConstructor = constructor;
     }
 
     /**
      * Executes the query against a model's index and returns the matching results.
      *
-     * @param {Model.constructor} model - The model class that contains the `fromData` method for constructing models from data.
-     * @param {Object<string, Model>} index - The index dataset to search through.
+     * @param {Object} query The structured query.
      * @returns {Array<Model>} The models that match the query.
      */
-    execute(model, index) {
-        return Object.values(index)
+    query(query) {
+        const splitQuery = this.#splitQuery(query);
+
+        return Object.values(this.#index)
             .filter(m =>
-                this._splitQuery(this.query)
-                    .map(query => Boolean(this._matchesQuery(m, query)))
+                splitQuery
+                    .map(q => Boolean(this.#matchesQuery(m, q)))
                     .every(c => c),
             )
-            .map(m => model.fromData(m));
+            .map(m => this.#modelConstructor.fromData(m));
     }
 
     /**
@@ -72,26 +82,31 @@ class Query {
      * @param {Object} inputQuery - The query to match against.
      * @returns {boolean} True if the subject matches the query, otherwise false.
      */
-    _matchesQuery(subject, inputQuery) {
-        if (['string', 'number', 'boolean'].includes(typeof inputQuery)) return subject === inputQuery;
+    #matchesQuery(subject, inputQuery) {
+        if (['string', 'number', 'boolean'].includes(typeof inputQuery))
+            return subject === inputQuery;
 
-        if (inputQuery?.$is !== undefined && subject === inputQuery.$is) return true;
+        if (inputQuery?.$is !== undefined && subject === inputQuery.$is)
+            return true;
 
         if (inputQuery?.$contains !== undefined) {
-            if (subject.includes?.(inputQuery.$contains)) return true;
+            if (subject.includes?.(inputQuery.$contains))
+                return true;
 
             for (const value of subject) {
-                if (this._matchesQuery(value, inputQuery.$contains)) return true;
+                if (this.#matchesQuery(value, inputQuery.$contains))
+                    return true;
             }
         }
 
         for (const key of Object.keys(inputQuery)) {
             if (!['$is', '$contains'].includes(key))
-                if (this._matchesQuery(subject[key], inputQuery[key])) return true;
+                if (this.#matchesQuery(subject[key], inputQuery[key]))
+                    return true;
         }
 
         return false;
-    };
+    }
 
     /**
      * Recursively splits an object into an array of objects,
@@ -105,14 +120,14 @@ class Query {
      * @returns {Array<Object>} An array of objects, where each object contains a single key-value pair
      *                         from the original query or its nested objects.
      */
-    _splitQuery(query) {
+    #splitQuery(query) {
         return Object.entries(query)
             .flatMap(([key, value]) =>
                 typeof value === 'object' && value !== null && !Array.isArray(value)
-                    ? this._splitQuery(value).map(nestedObj => ({[key]: nestedObj}))
+                    ? this.#splitQuery(value).map(nestedObj => ({[key]: nestedObj}))
                     : {[key]: value},
             );
     }
 }
 
-export default Query;
+export default FindIndex;

package/src/{type → data}/Model.js

@@ -1,5 +1,5 @@
-import SchemaCompiler from '../SchemaCompiler.js';
-import StringType from './simple/StringType.js';
+import Schema from '../Schema.js';
+import StringType from './properties/StringType.js';
 import _ from 'lodash';
 import {monotonicFactory} from 'ulid';
 
@@ -51,10 +51,9 @@ class Model {
     /**
      * Serializes the model instance into an object, optionally retaining complex types.
      *
-     * @param {boolean} [simple=true] - Determines whether to format the output using only JSON serialisable types.
      * @returns {Object} - A serialized representation of the model.
      */
-    toData(simple = true) {
+    toData() {
         const model = {...this};
 
         for (const [name, property] of Object.entries(this.constructor)) {
@@ -70,21 +69,6 @@ class Model {
                 }
                 return value;
             }),
-            (key, value) => {
-                if (!simple) {
-                    if (this.constructor[key]) {
-                        if (this.constructor[key].name.endsWith('Date')) {
-                            return new Date(value);
-                        }
-
-                        if (this.constructor[key].name.endsWith('ArrayOf(Date)')) {
-                            return value.map(d => new Date(d));
-                        }
-                    }
-                }
-
-                return value;
-            },
         );
     }
 
@@ -95,7 +79,7 @@ class Model {
      * @throws {ValidationError} - Throws this error if validation fails.
      */
     validate() {
-        return SchemaCompiler.compile(this.constructor).validate(this);
+        return Schema.compile(this.constructor).validate(this);
     }
 
     /**
@@ -210,12 +194,12 @@ class Model {
             .concat(
                 Object.entries(this)
                     .filter(([_name, type]) =>
-                            type?._type === 'array' && this.isModel(
-                                typeof type._items === 'function' &&
-                                !/^class/.test(Function.prototype.toString.call(type._items)) ?
-                                    type._items() : type._items,
-                            ),
-                    ).map(([name, _type]) => `${name}.[*].id`),
+                        !/^class/.test(Function.prototype.toString.call(type)) || type.toString().includes('Array'),
+                    )
+                    .filter(([_name, type]) =>
+                        this.isModel(type._items ?? type()._items ?? type),
+                    )
+                    .map(([name, _type]) => `${name}.[*].id`),
             )
             .concat(this.indexedProperties());
     }
@@ -244,12 +228,12 @@ class Model {
         for (const [name, value] of Object.entries(data)) {
             if (this[name]?._resolved) continue;
 
-            if (this[name].name.endsWith('Date')) {
+            if (this[name]?.name.endsWith('Date')) {
                 model[name] = new Date(value);
                 continue;
             }
 
-            if (this[name].name.endsWith('ArrayOf(Date)')) {
+            if (this[name]?.name.endsWith('ArrayOf(Date)')) {
                 model[name] = data[name].map(d => new Date(d));
                 continue;
             }
@@ -304,12 +288,12 @@ class Model {
      * @example
      * export default class TestModel {
      *     static {
+     *         this.withName('TestModel');
      *         this.string = Persist.Type.String;
-     *         Object.defineProperty(this, 'name', {value: 'TestModel'});
      *     }
      * }
      */
-    static setMinifiedName(name) {
+    static withName(name) {
         Object.defineProperty(this, 'name', {value: name});
     }
 }

package/src/data/Property.js

@@ -0,0 +1,19 @@
+import ArrayType from './properties/ArrayType.js';
+import BooleanType from './properties/BooleanType.js';
+import CustomType from './properties/CustomType.js';
+import DateType from './properties/DateType.js';
+import NumberType from './properties/NumberType.js';
+import SlugType from './properties/SlugType.js';
+import StringType from './properties/StringType.js';
+
+const Property = {
+    Array: ArrayType,
+    Boolean: BooleanType,
+    Custom: CustomType,
+    Date: DateType,
+    Number: NumberType,
+    Slug: SlugType,
+    String: StringType,
+};
+
+export default Property;

package/src/data/SearchIndex.js

@@ -1,5 +1,12 @@
 import lunr from 'lunr';
 
+export class SearchResult {
+    constructor(model, score) {
+        this.model = model;
+        this.score = score;
+    }
+}
+
 export default class SearchIndex {
     #index;
     #model;
@@ -13,11 +20,19 @@ export default class SearchIndex {
         }
     }
 
+    /**
+     *
+     * @param {string} query
+     * @return {Array<SearchResult>}
+     */
     search(query) {
-        return (this.#compiledIndex ?? this.#compileIndex()).search(query).map(doc => ({
-            score: doc.score,
-            model: this.#model.fromData(this.#index[doc.ref]),
-        }));
+        return this.searchIndex
+            .search(query)
+            .map(doc => new SearchResult(this.#model.fromData(this.#index[doc.ref]), doc.score));
+    }
+
+    get searchIndex() {
+        return this.#compiledIndex ?? this.#compileIndex();
     }
 
     #compileIndex() {

package/src/{type/complex → data/properties}/ArrayType.js

@@ -1,4 +1,4 @@
-import Type from '../Type.js';
+import Type from './Type.js';
 
 /**
  * Represents an array type definition, allowing the specification of an array of a certain type.

package/src/{type/simple → data/properties}/BooleanType.js

@@ -1,4 +1,4 @@
-import Type from '../Type.js';
+import Type from './Type.js';
 
 /**
  * Class representing a boolean type.

package/src/{type/complex → data/properties}/CustomType.js

@@ -1,4 +1,4 @@
-import Type from '../Type.js';
+import Type from './Type.js';
 import ajv from 'ajv';
 
 /**

package/src/{type/simple → data/properties}/DateType.js

@@ -1,4 +1,4 @@
-import Type from '../Type.js';
+import Type from './Type.js';
 
 /**
  * Class representing a date type with ISO date-time format.

package/src/{type/simple → data/properties}/NumberType.js

@@ -1,4 +1,4 @@
-import Type from '../Type.js';
+import Type from './Type.js';
 
 /**
  * Class representing a number type.

package/src/{type/resolved → data/properties}/ResolvedType.js

@@ -1,4 +1,4 @@
-import Type from '../Type.js';
+import Type from './Type.js';
 
 /**
  * Class representing a resolved type.
@@ -39,6 +39,7 @@ class ResolvedType extends Type {
      * @returns {ResolvedType} A subclass of `ResolvedType` customized for the provided property.
      */
     static of(property) {
+        const that = this;
         class ResolvedTypeOf extends ResolvedType {
             /**
              * Converts the resolved type to a string, displaying the resolved property.
@@ -46,7 +47,7 @@ class ResolvedType extends Type {
              * @returns {string} A string representing the resolved type, including the property.
              */
             static toString() {
-                return `ResolvedTypeOf(${property})`;
+                return `${that.toString()}Of(${property})`;
             }
         }
 

package/src/{type/simple → data/properties}/StringType.js

@@ -1,4 +1,4 @@
-import Type from '../Type.js';
+import Type from './Type.js';
 
 /**
  * Class representing a string type.