@acodeninja/persist 3.0.0-next.2 → 3.0.0-next.20

package/src/Persist.js

@@ -1,45 +1,44 @@
-import Type from './type/index.js';
-import enableTransactions from './Transactions.js';
+import Connection from './Connection.js';
+import Model from './data/Model.js';
+import Property from './data/Property.js';
+import {ValidationError} from './Schema.js';
 
 /**
  * @class Persist
  */
 class Persist {
-    static _engine = {};
-    /**
-     * @memberof Persist
-     * @type {Type}
-     * @static
-     */
-    static Type = Type;
+    static Property = Property;
+    static Model = Model;
+    static Connection = Connection;
+
+    static Errors = {
+        ValidationError,
+    };
+
+    static #connections = new Map();
 
     /**
-     * @function getEngine
-     * @memberof Persist
-     * @static
-     * @param {string} group - Name of the group containing the engine
-     * @param {Engine} engine - The engine class you wish to retrieve
-     * @return {Engine|null}
+     * Register a new connection.
+     * @param {string} name
+     * @param {StorageEngine} storage
+     * @param {Array<Model.constructor>} models
+     * @return {Connection}
      */
-    static getEngine(group, engine) {
-        return this._engine[group]?.[engine.name] ?? null;
+    static registerConnection(name, storage, models) {
+        const connection = new Connection(storage, models);
+
+        Persist.#connections.set(name, connection);
+
+        return connection;
     }
 
     /**
-     * @function addEngine
-     * @memberof Persist
-     * @static
-     * @param {string} group - Name of the group containing the engine
-     * @param {Engine} engine - The engine class you wish to configure and add to the group
-     * @param {object?} configuration - The configuration to use with the engine
+     * Get a persist connection by its name.
+     * @param {string} name
+     * @return {Connection|undefined}
      */
-    static addEngine(group, engine, configuration) {
-        if (!this._engine[group]) this._engine[group] = {};
-
-        this._engine[group][engine.name] =
-            configuration.transactions ?
-                enableTransactions(engine.configure(configuration)) :
-                engine.configure(configuration);
+    static getConnection(name) {
+        return Persist.#connections.get(name);
     }
 }
 

package/src/Schema.js

@@ -0,0 +1,175 @@
+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);
+
+        /**
+         * Recursively builds a JSON-schema-like object from a model or schema segment.
+         *
+         * Handles both `Model` instances and schema property definitions,
+         * including nested models and required property rules.
+         *
+         * @param {Object|Model|Type} schemaSegment - A model or a property descriptor.
+         * @returns {Object} A JSON schema representation of the input segment.
+         */
+        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} modelConstructor - The model class.
+     * @param {Record<string, Model>} index - The index dataset to search through.
      */
-    constructor(query) {
-        this.query = query;
+    constructor(modelConstructor, index) {
+        this.#index = index;
+        this.#modelConstructor = modelConstructor;
     }
 
     /**
      * 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,32 @@ 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 (typeof subject[Symbol.iterator] === 'function')
+                for (const value of subject) {
+                    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 +121,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,16 +79,16 @@ 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);
     }
 
     /**
      * Extracts data from the model based on the indexed properties defined in the class.
-     *
+     * Includes the ID of any linked models.
      * @returns {Object} - A representation of the model's indexed data.
      */
     toIndexData() {
-        return this._extractData(this.constructor.indexedProperties());
+        return this._extractData(this.constructor.indexedPropertiesResolved());
     }
 
     /**
@@ -167,6 +151,14 @@ class Model {
      * @static
      */
     static get required() {
+        /**
+         * A subclass of the current model with the `_required` flag set to `true`.
+         * Used to indicate that the property is required during validation or schema generation.
+         *
+         * @class
+         * @extends {Model}
+         * @private
+         */
         class Required extends this {
             static _required = true;
         }
@@ -179,6 +171,10 @@ class Model {
     /**
      * Returns a list of properties that are indexed.
      *
+     * - To link to properties of a model use `<name>`
+     * - To link to properties of linked models use `<model>.<name>`
+     * - To link to properties of many linked models use `<model>.[*].<name>`
+     *
      * @returns {Array<string>} - The indexed properties.
      * @abstract
      * @static
@@ -187,6 +183,25 @@ class Model {
         return [];
     }
 
+    /**
+     * Returns a list of properties that are indexed including links to other models.
+     *
+     * @returns {Array<string>} - The indexed properties.
+     * @abstract
+     * @static
+     */
+    static indexedPropertiesResolved() {
+        return [
+            ...Object.entries(this)
+                .filter(([_name, type]) => !type._type && (this.isModel(type) || this.isModel(type())))
+                .map(([name, _type]) => `${name}.id`),
+            ...Object.entries(this)
+                .filter(([_name, type]) => !type._type && !this.isModel(type) && !type._items?._type && (this.isModel(type._items) || this.isModel(type()._items)))
+                .map(([name, _type]) => `${name}.[*].id`),
+            ...this.indexedProperties(),
+        ];
+    }
+
     /**
      * Returns a list of properties used for search.
      *
@@ -211,12 +226,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;
             }
@@ -271,12 +286,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

@@ -0,0 +1,106 @@
+import lunr from 'lunr';
+
+/**
+ * Represents a single search result with the associated model instance and its relevance score.
+ *
+ * @class SearchResult
+ */
+export class SearchResult {
+    constructor(model, score) {
+        this.model = model;
+        this.score = score;
+    }
+}
+
+/**
+ * A full-text search index wrapper using Lunr.js for a given model.
+ * Supports indexing and querying model data.
+ *
+ * @class SearchIndex
+ */
+export default class SearchIndex {
+    #index;
+    #model;
+    #compiledIndex;
+
+    /**
+     * Initializes the search index for the provided model.
+     *
+     * @param {Model} model - The model definition to use for indexing.
+     * @param {Object.<string, Object>} index - A dictionary of model data, keyed by ID.
+     * @throws {NoIndexAvailableSearchIndexError} If the model has no searchable properties.
+     */
+    constructor(model, index) {
+        this.#index = index;
+        this.#model = model;
+        if (model.searchProperties().length === 0) {
+            throw new NoIndexAvailableSearchIndexError(this.#model);
+        }
+    }
+
+    /**
+     * Performs a search query on the compiled Lunr index.
+     *
+     * @param {string} query - The search string.
+     * @return {Array<SearchResult>} An array of search results with model instances and scores.
+     */
+    search(query) {
+        return this.searchIndex
+            .search(query)
+            .map(doc => new SearchResult(this.#model.fromData(this.#index[doc.ref]), doc.score));
+    }
+
+    /**
+     * Lazily compiles and returns the Lunr index instance.
+     *
+     * @return {lunr.Index} The compiled Lunr index.
+     */
+    get searchIndex() {
+        return this.#compiledIndex ?? this.#compileIndex();
+    }
+
+    /**
+     * Compiles the Lunr index using the model's search properties.
+     *
+     * @return {lunr.Index} The compiled Lunr index.
+     * @private
+     */
+    #compileIndex() {
+        const model = this.#model;
+        const index = this.#index;
+        this.#compiledIndex = lunr(function () {
+            this.ref('id');
+
+            for (const field of model.searchProperties()) {
+                this.field(field);
+            }
+
+            Object.values(index).forEach(function (doc) {
+                this.add(doc);
+            }, this);
+        });
+
+        return this.#compiledIndex;
+    }
+}
+
+/**
+ * Base error class for search index-related exceptions.
+ *
+ * @class SearchIndexError
+ * @extends {Error}
+ */
+export class SearchIndexError extends Error {
+}
+
+/**
+ * Thrown when a model does not have any properties defined for indexing.
+ *
+ * @class NoIndexAvailableSearchIndexError
+ * @extends {SearchIndexError}
+ */
+export class NoIndexAvailableSearchIndexError extends SearchIndexError {
+    constructor(model) {
+        super(`The model ${model.name} has no search properties`);
+    }
+}

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.