@acodeninja/persist 3.0.0-next.9 → 3.0.0

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 compiled schema, ready to validate instances of the model.
+     *
+     * @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 = [];
+                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: [],
+                            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,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);
     }
 
     /**
@@ -167,11 +151,21 @@ class Model {
      * @static
      */
     static get required() {
-        class Required extends this {
+        const ModelClass = this;
+
+        /**
+         * 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 ModelClass {
             static _required = true;
         }
 
-        Object.defineProperty(Required, 'name', {value: `${this.toString()}`});
+        Object.defineProperty(Required, 'name', {value: ModelClass.name});
 
         return Required;
     }
@@ -179,6 +173,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
@@ -195,29 +193,23 @@ class Model {
      * @static
      */
     static indexedPropertiesResolved() {
-        return []
-            .concat(
-                Object.entries(this)
-                    .filter(([_, type]) =>
-                        this.isModel(
-                            typeof type === 'function' &&
-                            !/^class/.test(Function.prototype.toString.call(type)) ?
-                                type() : type,
-                        ),
-                    )
-                    .map(([name, _]) => `${name}.id`),
-            )
-            .concat(
-                Object.entries(this)
-                    .filter(([_, type]) =>
-                            type?._type === 'array' && this.isModel(
-                                typeof type._items === 'function' &&
-                                !/^class/.test(Function.prototype.toString.call(type._items)) ?
-                                    type._items() : type._items,
-                            ),
-                    ).map(([name, _]) => `${name}.[*].id`),
-            )
-            .concat(this.indexedProperties());
+        const ModelClass = this;
+        return [
+            ...Object.entries(ModelClass.properties)
+                .filter(([name, type]) => !['indexedProperties', 'searchProperties'].includes(name) && !type._type && (ModelClass.isModel(type) || (typeof type === 'function' && ModelClass.isModel(type()))))
+                .map(([name, _type]) => `${name}.id`),
+            ...Object.entries(ModelClass.properties)
+                .filter(([_name, type]) => {
+                    return !Model.isModel(type) && (
+                        (type._type === 'array' && ModelClass.isModel(type._items))
+                        ||
+                        (!type._type && typeof type === 'function' && ModelClass.isModel(type()._items))
+                    );
+                })
+                .map(([name, _type]) => `${name}.[*].id`),
+            ...ModelClass.indexedProperties(),
+            'id',
+        ];
     }
 
     /**
@@ -239,17 +231,18 @@ class Model {
      * @static
      */
     static fromData(data) {
-        const model = new this();
+        const ModelClass = this;
+        const model = new ModelClass();
 
         for (const [name, value] of Object.entries(data)) {
-            if (this[name]?._resolved) continue;
+            if (ModelClass[name]?._resolved) continue;
 
-            if (this[name].name.endsWith('Date')) {
+            if (ModelClass[name]?.name.endsWith('Date')) {
                 model[name] = new Date(value);
                 continue;
             }
 
-            if (this[name].name.endsWith('ArrayOf(Date)')) {
+            if (ModelClass[name]?.name.endsWith('ArrayOf(Date)')) {
                 model[name] = data[name].map(d => new Date(d));
                 continue;
             }
@@ -284,7 +277,7 @@ class Model {
     static isDryModel(possibleDryModel) {
         try {
             return (
-                !this.isModel(possibleDryModel) &&
+                !Model.isModel(possibleDryModel) &&
                 Object.keys(possibleDryModel).includes('id') &&
                 new RegExp(/[A-Za-z]+\/[A-Z0-9]+/).test(possibleDryModel.id)
             );
@@ -302,15 +295,62 @@ class Model {
      * @static
      *
      * @example
-     * export default class TestModel {
+     * export default class TestModel extends Model {
      *     static {
-     *         this.string = Persist.Type.String;
-     *         Object.defineProperty(this, 'name', {value: 'TestModel'});
+     *         TestModel.withName('TestModel');
+     *         TestModel.string = Persist.Property.String;
      *     }
      * }
      */
-    static setMinifiedName(name) {
-        Object.defineProperty(this, 'name', {value: name});
+    static withName(name) {
+        const ModelClass = this;
+        Object.defineProperty(ModelClass, 'name', {value: name});
+    }
+
+    /**
+     * Discover model properties all the way up the prototype chain.
+     *
+     * @return {Model}
+     */
+    static get properties() {
+        const ModelClass = this;
+        const props = {};
+        const chain = [];
+
+        let current = ModelClass;
+        while (current !== Function.prototype) {
+            chain.push(current);
+            current = Object.getPrototypeOf(current);
+        }
+
+        for (const item of chain) {
+            for (const property of Object.getOwnPropertyNames(item)) {
+                if (
+                    [
+                        '_required',
+                        'fromData',
+                        'indexedProperties',
+                        'indexedPropertiesResolved',
+                        'isDryModel',
+                        'isModel',
+                        'length',
+                        'name',
+                        'properties',
+                        'prototype',
+                        'required',
+                        'searchProperties',
+                        'toString',
+                        'withName',
+                    ].includes(property)
+                ) continue;
+
+                if (Object.keys(props).includes(property)) continue;
+
+                props[property] = item[property];
+            }
+        }
+
+        return Object.assign(ModelClass, props);
     }
 }
 

package/src/data/Property.js

@@ -0,0 +1,21 @@
+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';
+import Type from './properties/Type.js';
+
+const Property = {
+    Array: ArrayType,
+    Boolean: BooleanType,
+    Custom: CustomType,
+    Date: DateType,
+    Number: NumberType,
+    Slug: SlugType,
+    String: StringType,
+    Type,
+};
+
+export default Property;