@acodeninja/persist 3.1.0-next.2 → 3.2.0-next.1

package/docs/storage-engines.md

@@ -23,6 +23,41 @@ export class Tag extends Persist.Model {
 await connection.put(new Tag({tag: 'documentation'}));
 ```
 
+### Versioning with S3 Buckets
+
+When you use versioning with an S3 Bucket, you may have to set `pragma` header and `ResponseCacheControl` metadata on all requests. This can be done by adding middleware for both the `build` and `serialize` steps for each request:
+
+```javascript
+import Persist from "@acodeninja/persist";
+import {S3Client} from "@aws-sdk/client-s3";
+import S3StorageEngine from "@acodeninja/persist/storage/s3";
+
+const client = new S3Client();
+
+client.middlewareStack.add(
+    (next, context) => (args) => {
+        args.request.headers['pragma'] = 'no-cache';
+        return next(args);
+    },
+    {step: 'build'},
+);
+
+client.middlewareStack.add(
+    (next, context) => (args) => {
+        args.input.ResponseCacheControl = 'no-cache';
+        return next(args);
+    },
+    {step: 'serialize'},
+);
+
+const connection = Persist.registerConnection('remote', new S3StorageEngine({
+    bucket: 'test-bucket',
+    client,
+}));
+```
+
+These changes will ensure that all requests are made with a `no-cache` header set for getting and putting objects to the S3 bucket.
+
 ## HTTP Storage StorageEngine
 
 To store models using an HTTP server, use the `HTTP` storage engine. When using the `HTTP` engine in the browser, refer to [code quirks](./code-quirks.md#using-http-engine-in-browser).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acodeninja/persist",
-  "version": "3.1.0-next.2",
+  "version": "3.2.0-next.1",
   "description": "A JSON based data modelling and persistence module with alternate storage mechanisms.",
   "type": "module",
   "scripts": {

package/src/Connection.js

@@ -483,10 +483,10 @@ export default class Connection {
      * Retrieve a search index to query at your leisure.
      *
      * @param {Model.constructor} modelConstructor
-     * @return {SearchIndex}
+     * @return {Promise<SearchIndex>}
      */
-    async getSearchIndex(modelConstructor) {
-        return await this.#storage.getSearchIndex(modelConstructor)
+    getSearchIndex(modelConstructor) {
+        return this.#storage.getSearchIndex(modelConstructor)
             .then(index => new SearchIndex(modelConstructor, index));
     }
 
@@ -504,13 +504,13 @@ export default class Connection {
     }
 
     /**
-     * Retrieve a index to query at your leisure.
+     * Retrieve an index to query at your leisure.
      *
      * @param {Model.constructor} modelConstructor
-     * @return {FindIndex}
+     * @return {Promise<FindIndex>}
      */
-    async getIndex(modelConstructor) {
-        return await this.#storage.getIndex(modelConstructor)
+    getIndex(modelConstructor) {
+        return this.#storage.getIndex(modelConstructor)
             .then(index => new FindIndex(modelConstructor, index));
     }
 
@@ -622,8 +622,14 @@ export default class Connection {
             if (propertyType.prototype instanceof Model) {
                 modelsThatLinkToThisSubject.set([propertyType.name, propertyName, 'one', 'down'], propertyType);
             }
-            // The model is a one to many link
 
+            propertyType._items?.forEach?.(i => {
+                if (i.prototype instanceof Model) {
+                    modelsThatLinkToThisSubject.set([i.name, propertyName, 'one', 'down'], i);
+                }
+            });
+
+            // The model is a one to many link
             if (propertyType._items?.prototype instanceof Model) {
                 modelsThatLinkToThisSubject.set([propertyType._items.name, propertyName, 'many', 'down'], propertyType);
             }
@@ -636,6 +642,12 @@ export default class Connection {
                     modelsThatLinkToThisSubject.set([modelName, propertyName, 'one', 'up'], propertyType);
                 }
 
+                propertyType._items?.forEach?.(i => {
+                    if (i === subjectModelConstructor) {
+                        modelsThatLinkToThisSubject.set([modelName, propertyName, 'one', 'up'], i);
+                    }
+                });
+
                 // The model is a one to many link
                 if (propertyType._items === subjectModelConstructor || propertyType._items?.prototype instanceof subjectModelConstructor) {
                     modelsThatLinkToThisSubject.set([modelName, propertyName, 'many', 'up'], propertyType);

package/src/Schema.js

@@ -38,8 +38,26 @@ class Schema {
         function BuildSchema(schemaSegment) {
             const thisSchema = {};
 
+            if (schemaSegment?._type === 'anyOf') {
+                thisSchema.anyOf = schemaSegment._items.map(item => Model.isModel(item) ?
+                    {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: schemaSegment._required ? ['id'] : [],
+                        properties: {
+                            id: {
+                                type: 'string',
+                                pattern: `^${item.toString()}/[A-Z0-9]+$`,
+                            },
+                        },
+                    } : BuildSchema(item),
+                );
+
+                return thisSchema;
+            }
+
             if (Model.isModel(schemaSegment)) {
-                thisSchema.required = [];
+                thisSchema.required = ['id'];
                 thisSchema.type = 'object';
                 thisSchema.additionalProperties = false;
                 thisSchema.properties = {
@@ -50,7 +68,7 @@ class Schema {
                 };
 
                 for (const [name, type] of Object.entries(schemaSegment)) {
-                    if (['indexedProperties', 'searchProperties'].includes(name)) continue;
+                    if (['indexedProperties', 'searchProperties', 'id'].includes(name)) continue;
 
                     const property = type instanceof Function && !type.prototype ? type() : type;
 
@@ -70,6 +88,7 @@ class Schema {
                                 },
                             },
                         };
+
                         continue;
                     }
 

package/src/data/FindIndex.js

@@ -102,7 +102,7 @@ class FindIndex {
 
         for (const key of Object.keys(inputQuery)) {
             if (!['$is', '$contains'].includes(key))
-                if (this.#matchesQuery(subject[key], inputQuery[key]))
+                if (this.#matchesQuery(subject?.[key], inputQuery[key]))
                     return true;
         }
 

package/src/data/Model.js

@@ -88,7 +88,7 @@ class Model {
      * @returns {Object} - A representation of the model's indexed data.
      */
     toIndexData() {
-        return this._extractData(this.constructor.indexedPropertiesResolved());
+        return this.#extractData(this.constructor.indexedPropertiesResolved());
     }
 
     /**
@@ -97,7 +97,7 @@ class Model {
      * @returns {Object} - A representation of the model's search data.
      */
     toSearchData() {
-        return this._extractData(this.constructor.searchProperties());
+        return this.#extractData(this.constructor.searchProperties());
     }
 
     /**
@@ -107,11 +107,11 @@ class Model {
      * @returns {Object} - The extracted data.
      * @private
      */
-    _extractData(keys) {
+    #extractData(keys) {
         const output = {id: this.id};
 
         for (const key of keys) {
-            if (_.has(this, key)) {
+            if (_.get(this, key)) {
                 _.set(output, key, _.get(this, key));
             }
 
@@ -196,7 +196,32 @@ class Model {
         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()))))
+                .filter(([name, type]) => {
+                    if (['indexedProperties', 'searchProperties'].includes(name)) return false;
+
+                    const includesSingleModel = (maybeIncludesSingleModel) => {
+                        if (maybeIncludesSingleModel._type === 'array') return false;
+
+                        if (Model.isModel(maybeIncludesSingleModel)) return true;
+
+                        if (maybeIncludesSingleModel._items?.some?.(i => ModelClass.isModel(i))) return true;
+
+                        return false;
+                    };
+
+                    if (includesSingleModel(type)) return true;
+
+                    if (
+                        typeof type === 'function' &&
+                        // This differentiates between a function and a class.
+                        // A class prototype is non-writable.
+                        !Object.getOwnPropertyDescriptor(type, 'prototype')
+                    ) {
+                        if (includesSingleModel(type())) return true;
+                    }
+
+                    return false;
+                })
                 .map(([name, _type]) => `${name}.id`),
             ...Object.entries(ModelClass.properties)
                 .filter(([_name, type]) => {

package/src/data/Property.js

@@ -1,3 +1,4 @@
+import AnyType from './properties/AnyType.js';
 import ArrayType from './properties/ArrayType.js';
 import BooleanType from './properties/BooleanType.js';
 import CustomType from './properties/CustomType.js';
@@ -8,6 +9,7 @@ import StringType from './properties/StringType.js';
 import Type from './properties/Type.js';
 
 const Property = {
+    Any: AnyType,
     Array: ArrayType,
     Boolean: BooleanType,
     Custom: CustomType,

package/src/data/SearchIndex.js

@@ -13,7 +13,7 @@ export class SearchResult {
 }
 
 /**
- * A full-text search index wrapper using Lunr.js for a given model.
+ * A full-text search index wrapper using Fuse.js for a given model.
  * Supports indexing and querying model data.
  *
  * @class SearchIndex
@@ -39,7 +39,7 @@ export default class SearchIndex {
     }
 
     /**
-     * Performs a search query on the compiled Lunr index.
+     * Performs a search query on the compiled index.
      *
      * @param {string} query - The search string.
      * @return {Array<SearchResult>} An array of search results with model instances and scores.
@@ -51,18 +51,18 @@ export default class SearchIndex {
     }
 
     /**
-     * Lazily compiles and returns the Lunr index instance.
+     * Lazily compiles and returns the index instance.
      *
-     * @return {Fuse} The compiled Lunr index.
+     * @return {Fuse} The compiled index.
      */
     get searchIndex() {
         return this.#compiledIndex ?? this.#compileIndex();
     }
 
     /**
-     * Compiles the Lunr index using the model's search properties.
+     * Compiles the index using the model's search properties.
      *
-     * @return {Fuse} The compiled Lunr index.
+     * @return {Fuse} The compiled index.
      * @private
      */
     #compileIndex() {

package/src/data/properties/AnyType.js

@@ -0,0 +1,87 @@
+import Type from './Type.js';
+
+/**
+ * Represents a union type definition, allowing the specification of a value that can be one of several types.
+ * This class is used to create type definitions for union types that can be validated and used in schemas.
+ *
+ * @class AnyType
+ */
+class AnyType {
+    /**
+     * Creates a new type definition for a union of the specified types.
+     *
+     * The `of` method defines a union type where the value can be any one of the specified types. It returns a
+     * class representing this union type, which can further be marked as required using the `required` getter.
+     *
+     * @param {...(Type|Model)} types - The types or models that the union can contain. A value must match at least one of these types.
+     * @returns {Type} A new class representing a union of the specified types.
+     *
+     * @example
+     * const stringOrNumber = AnyType.of(StringType, NumberType);
+     * const requiredStringOrBoolean = AnyType.of(StringType, BooleanType).required;
+     */
+    static of(...types) {
+        /**
+         * @class AnyOf
+         * @extends Type
+         * Represents a union of specific types.
+         */
+        class AnyOf extends Type {
+            /** @type {string} The data type, which is 'anyOf' */
+            static _type = 'anyOf';
+
+            /** @type {Type[]} The array of types that are allowed in the union */
+            static _items = types;
+
+            /**
+             * Returns the string representation of the union type.
+             *
+             * @returns {string} The string representation of the union type.
+             */
+            static toString() {
+                return `AnyOf(${types.map(t => t.toString()).join('|')})`;
+            }
+
+            /**
+             * Marks the union type as required.
+             *
+             * @returns {Type} A new class representing a required union of the specified types.
+             *
+             * @example
+             * const requiredStringOrNumber = AnyType.of(StringType, NumberType).required;
+             */
+            static get required() {
+                const ThisType = this;
+
+                /**
+                 * @class RequiredAnyOf
+                 * @extends AnyOf
+                 * Represents a required union of specific types.
+                 */
+                class Required extends ThisType {
+                    /** @type {boolean} Indicates that the union type is required */
+                    static _required = true;
+
+                    /**
+                     * Returns the string representation of the required union type.
+                     *
+                     * @returns {string} The string representation of the required union type.
+                     */
+                    static toString() {
+                        return `RequiredAnyOf(${types.map(t => t.toString()).join('|')})`;
+                    }
+                }
+
+                Object.defineProperty(Required, 'name', {value: `Required${ThisType.name}`});
+
+                return Required;
+            }
+        }
+
+        Object.defineProperty(AnyOf, 'name', {value: AnyOf.toString()});
+
+        return AnyOf;
+    }
+}
+
+export default AnyType;