@warp-drive/core 5.8.0-beta.0 → 5.8.0-beta.2

package/dist/unpkg/dev/types/schema/fields.js

@@ -0,0 +1,505 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+
+/**
+ * Options signature for Legacy Attributes.
+ */
+
+/**
+ * A generic "field" that can be used to define
+ * primitive value fields.
+ *
+ * Replaces "attribute" for primitive value fields.
+ * Can also be used to eject from deep-tracking of
+ * objects or arrays.
+ *
+ * A major difference between "field" and "attribute"
+ * is that "type" points to a legacy transform on
+ * "attribute" that a serializer *might* use, while
+ * "type" points to a new-style transform on "field"
+ * that a record implmentation *must* use.
+ *
+ * @public
+ */
+
+/**
+ * A field that can be used to alias one key to another
+ * key present in the cache version of the resource.
+ *
+ * Unlike DerivedField, an AliasField may write to its
+ * source when a record is in an editable mode.
+ *
+ * ~~AliasFields may utilize a transform, specified by type,
+ * to pre/post process the raw data for the field.~~ (not yet implemented)
+ *
+ * An AliasField may also specify a `kind` via options.
+ * `kind` may be any other valid field kind other than
+ *
+ * - `@hash`
+ * - `@id`
+ * - `@local`
+ * - `derived`
+ *
+ * This allows an AliasField to rename any field in the cache.
+ *
+ * Alias fields are generally intended to be used to support migrating
+ * between different schemas, though there are times where they are useful
+ * as a form of advanced derivation when used with a transform. For instance,
+ * an AliasField could be used to expose both a string and a Date version of the
+ * same field, with both being capable of being written to.
+ *
+ * @public
+ */
+
+/**
+ * A field that can be used to alias one key to another
+ * key present in the cache version of the resource.
+ *
+ * Unlike DerivedField, an AliasField may write to its
+ * source when a record is in an editable mode.
+ *
+ * ~~AliasFields may utilize a transform, specified by type,
+ * to pre/post process the raw data for the field.~~ (not yet implemented)
+ *
+ * An AliasField may also specify a `kind` via options.
+ * `kind` may be any other valid field kind other than
+ *
+ * - `@hash`
+ * - `@id`
+ * - `@local`
+ * - `derived`
+ *
+ * This allows an AliasField to rename any field in the cache.
+ *
+ * Alias fields are generally intended to be used to support migrating
+ * between different schemas, though there are times where they are useful
+ * as a form of advanced derivation when used with a transform. For instance,
+ * an AliasField could be used to expose both a string and a Date version of the
+ * same field, with both being capable of being written to.
+ *
+ * @public
+ */
+
+/**
+ * A field that can be used to alias one key to another
+ * key present in the cache version of the resource.
+ *
+ * Unlike DerivedField, an AliasField may write to its
+ * source when a record is in an editable mode.
+ *
+ * AliasFields may utilize a transform, specified by type,
+ * to pre/post process the field.
+ *
+ * An AliasField may also specify a `kind` via options.
+ * `kind` may be any other valid field kind other than
+ *
+ * - `@hash`
+ * - `@id`
+ * - `@local`
+ * - `derived`
+ *
+ * This allows an AliasField to rename any field in the cache.
+ *
+ * Alias fields are generally intended to be used to support migrating
+ * between different schemas, though there are times where they are useful
+ * as a form of advanced derivation when used with a transform. For instance,
+ * an AliasField could be used to expose both a string and a Date version of the
+ * same field, with both being capable of being written to.
+ *
+ * @public
+ */
+
+/**
+ * Represents a field whose value is the primary
+ * key of the resource.
+ *
+ * This allows any field to serve as the primary
+ * key while still being able to drive identity
+ * needs within the system.
+ *
+ * This is useful for resources that use for instance
+ * 'uuid', 'urn' or 'entityUrn' or 'primaryKey' as their
+ * primary key field instead of 'id'.
+ *
+ * @public
+ */
+
+/**
+ * Represents a specialized field whose computed value
+ * will be used as the primary key of a schema-object
+ * for serializability and comparison purposes.
+ *
+ * This field functions similarly to derived fields in that
+ * it is non-settable, derived state but differs in that
+ * it is only able to compute off of cache state and is given
+ * no access to a record instance.
+ *
+ * This means that if a hashing function wants to compute its value
+ * taking into account transformations and derivations it must
+ * perform those itself.
+ *
+ * A schema-array can declare its "key" value to be `@hash` if
+ * the schema-objects it contains have such a field.
+ *
+ * Only one hash field is permittable per schema-object, and
+ * it should be placed in the `ResourceSchema`'s `@id` field
+ * in place of an `IdentityField`.
+ *
+ * @public
+ */
+
+/**
+ * Represents a field whose value is a local
+ * value that is not stored in the cache, nor
+ * is it sent to the server.
+ *
+ * Local fields can be written to, and their
+ * value is both memoized and reactive (though
+ * not deep-tracked).
+ *
+ * Because their state is not derived from the cache
+ * data or the server, they represent a divorced
+ * uncanonical source of state.
+ *
+ * For this reason Local fields should be used sparingly.
+ *
+ * Currently, while we document this feature here,
+ * only allow our own ReactiveResource default fields to
+ * utilize them and the feature should be considered private.
+ *
+ * Example use cases that drove the creation of local
+ * fields are states like `isDestroying` and `isDestroyed`
+ * which are specific to a record instance but not
+ * stored in the cache. We wanted to be able to drive
+ * these fields from schema the same as all other fields.
+ *
+ * Don't make us regret this decision.
+ *
+ * @public
+ */
+
+/**
+ * Represents a field whose value is an object
+ * with keys pointing to values that are primitive
+ * values.
+ *
+ * If values of the keys are not primitives, or
+ * if the key/value pairs have well-defined shape,
+ * use 'schema-object' instead.
+ *
+ * @public
+ */
+
+/**
+ * Represents a field whose value is an object
+ * with a well-defined structure described by
+ * a schema-object (a non-resource schema).
+ *
+ * If the object's structure is not well-defined,
+ * use 'object' instead.
+ *
+ * By default, a SchemaObject within
+ *
+ * @public
+ */
+
+/**
+ * Represents a field whose value is an array
+ * of primitive values.
+ *
+ * If the array's elements are not primitive
+ * values, use 'schema-array' instead.
+ *
+ * @public
+ */
+
+/**
+ * Represents a field whose value is an array
+ * of objects with a well-defined structure
+ * described by a non-resource schema.
+ *
+ * If the array's elements are not well-defined,
+ * use 'array' instead.
+ *
+ * @public
+ */
+
+/**
+ * Represents a field whose value is derived
+ * from other fields in the schema.
+ *
+ * The value is read-only, and is not stored
+ * in the cache, nor is it sent to the server.
+ *
+ * Usage of derived fields should be minimized
+ * to scenarios where the derivation is known
+ * to be safe. For instance, derivations that
+ * required fields that are not always loaded
+ * or that require access to related resources
+ * that may not be loaded should be avoided.
+ *
+ * @public
+ */
+
+/**
+ * Represents a field that is a reference to
+ * another resource.
+ *
+ * SUPPORT FOR THIS FEATURE IS NOT YET IMPLEMENTED
+ * BY ReactiveResource
+ *
+ * @public
+ */
+
+/**
+ * Represents a field that is a reference to
+ * a collection of other resources, potentially
+ * paginate.
+ *
+ * SUPPORT FOR THIS FEATURE IS NOT YET IMPLEMENTED
+ * BY ReactiveResource
+ *
+ * @public
+ */
+
+/**
+ * > [!CAUTION]
+ * > This Field is LEGACY
+ * > It cannot be used with PolarisMode
+ *
+ * A generic "field" that can be used to define
+ * primitive value fields.
+ *
+ * If the field points to an object or array,
+ * it will not be deep-tracked.
+ *
+ * Transforms when defined are legacy transforms
+ * that a serializer *might* use, but their usage
+ * is not guaranteed.
+ *
+ * @public
+ */
+
+/**
+ * > [!CAUTION]
+ * > This Field is LEGACY
+ *
+ * Represents a field that is a reference to
+ * another resource.
+ *
+ * This is the legacy version of the `ResourceField`.
+ *
+ * @public
+ */
+
+/**
+ * > [!CAUTION]
+ * > This Field is LEGACY
+ *
+ * Represents a field that is a reference to
+ * another resource.
+ *
+ * This is the legacy version of the `ResourceField`.
+ *
+ * @public
+ */
+
+/**
+ * > [!CAUTION]
+ * > This Field is LEGACY
+ *
+ * Represents a field that is a reference to
+ * a collection of other resources.
+ *
+ * This is the legacy version of the `CollectionField`.
+ *
+ * @public
+ */
+
+/**
+ * > [!CAUTION]
+ * > This Field is LEGACY
+ *
+ * Represents a field that is a reference to
+ * a collection of other resources.
+ *
+ * This is the legacy version of the `CollectionField`.
+ *
+ * @public
+ */
+
+/**
+ * A union of all possible LegacyMode field schemas.
+ *
+ * Available field schemas are:
+ *
+ * - {@link GenericField}
+ * - {@link LegacyAliasField}
+ * - {@link LocalField}
+ * - {@link ObjectField}
+ * - {@link SchemaObjectField}
+ * - {@link ArrayField}
+ * - {@link SchemaArrayField}
+ * - {@link DerivedField}
+ * - {@link ResourceField | ResourceField (not yet implemented)}
+ * - {@link CollectionField | CollectionField (not yet implemented)}
+ * - {@link LegacyAttributeField}
+ * - {@link LegacyBelongsToField}
+ * - {@link LegacyHasManyField}
+ *
+ * @public
+ */
+
+/**
+ * A union of all possible PolarisMode field schemas.
+ *
+ * Available field schemas are:
+ *
+ * - {@link GenericField}
+ * - {@link PolarisAliasField}
+ * - {@link LocalField}
+ * - {@link ObjectField}
+ * - {@link SchemaObjectField}
+ * - {@link ArrayField}
+ * - {@link SchemaArrayField}
+ * - {@link DerivedField}
+ * - {@link ResourceField | ResourceField (not yet implemented)}
+ * - {@link CollectionField | CollectionField (not yet implemented)}
+ * - {@link LinksModeBelongsToField}
+ * - {@link LinksModeHasManyField}
+ *
+ * @public
+ */
+
+/**
+ * A union of all possible LegacyMode and PolarisMode
+ * field schemas.
+ *
+ * You likely will want to use PolarisModeFieldSchema,
+ * LegacyModeFieldSchema, or ObjectFieldSchema instead
+ * as appropriate as they are more specific and will
+ * provide better guidance around what is valid.
+ *
+ * @public
+ */
+
+/**
+ * A union of all possible LegacyMode and PolarisMode
+ * field schemas that represent data that could be in
+ * the cache.
+ *
+ * In other words this will not include types like alias
+ * fields, local fields, or derived fields.
+ *
+ * @public
+ */
+
+/**
+ * A union of all possible field schemas that can be
+ * used in an ObjectSchema.
+ *
+ * @public
+ */
+
+/**
+ * Represents a schema for a primary resource in PolarisMode.
+ *
+ * Primary resources are objects with a unique identity of their
+ * own which may allow them to appear in relationships, or in multiple
+ * response documents.
+ *
+ * @public
+ */
+
+/**
+ * Represents a schema for a primary resource in LegacyMode
+ *
+ * Primary resources are objects with a unique identity of their
+ * own which may allow them to appear in relationships, or in multiple
+ * response documents.
+ *
+ * @public
+ */
+
+/**
+ * A type which represents a valid JSON schema
+ * definition for either a PolarisMode or a
+ * LegacyMode resource.
+ *
+ * Note, this is separate from the type returned
+ * by the SchemaService which provides fields as a Map
+ * instead of as an Array.
+ *
+ * @public
+ */
+
+/**
+ * Represents a schema for an object that is not
+ * a primary resource (has no unique identity of its own).
+ *
+ * ObjectSchemas may not currently contain relationships.
+ *
+ * @public
+ */
+
+/**
+ * A trait for use on a PolarisMode record
+ */
+
+/**
+ * A trait for use on a LegacyMode record
+ */
+
+/**
+ * A union of
+ * - {@link LegacyTrait}
+ * - {@link PolarisTrait}
+ */
+
+/**
+ * A no-op type utility that enables type-checking resource schema
+ * definitions.
+ *
+ * Will return the passed in schema.
+ *
+ * This will not validate relationship inverses or related types,
+ * as doing so would require a full schema graph to be passed in
+ * and no cycles in the graph to be present.
+ *
+ * @public
+ */
+function resourceSchema(schema) {
+  return schema;
+}
+
+/**
+ * A no-op type utility that enables type-checking object schema
+ * definitions.
+ *
+ * Will return the passed in schema.
+ *
+ * @public
+ */
+function objectSchema(schema) {
+  return schema;
+}
+
+/**
+ * A type utility to narrow a schema to a ResourceSchema
+ *
+ * @public
+ */
+function isResourceSchema(schema) {
+  return schema?.identity?.kind === '@id';
+}
+
+/**
+ * A type utility to narrow a schema to LegacyResourceSchema
+ *
+ * @public
+ */
+function isLegacyResourceSchema(schema) {
+  return isResourceSchema(schema) && schema.legacy === true;
+}
+export { isLegacyResourceSchema, isResourceSchema, objectSchema, resourceSchema };

package/dist/unpkg/dev/types/symbols.js

@@ -0,0 +1,84 @@
+import { getOrSetGlobal } from './-private.js';
+const RecordStore = getOrSetGlobal('Store', Symbol('Store'));
+
+/**
+ * Symbol for the name of a resource, transformation
+ * or derivation.
+ *
+ * ### With Resources
+ *
+ * This is an optional feature that can be used by
+ * record implementations to provide a typescript
+ * hint for the type of the resource.
+ *
+ * When used, WarpDrive APIs can
+ * take advantage of this to provide better type
+ * safety and intellisense.
+ *
+ * ### With Derivations
+ *
+ * Required for derivations registered with
+ * `store.registerDerivation(derivation)`.
+ *
+ * ```ts
+ * function concat(record: object, options: ObjectValue | null, prop: string): string {}
+ * concat[Name] = 'concat';
+ * ```
+ *
+ * ### With Transforms
+ *
+ * Required for new-style transformations registered
+ * with `store.registerTransform(transform)`.
+ *
+ * For legacy transforms, if not used,
+ * `attr<Transform>('name')` will allow any string name.
+ * `attr('name')` will always allow any string name.
+ *
+ * If used, `attr<Transform>('name')` will enforce
+ * that the name is the same as the transform name.
+ *
+ * @type {Symbol}
+ */
+const Type = getOrSetGlobal('$type', Symbol('$type'));
+
+/**
+ * Symbol for the type of a resource.
+ *
+ * This is an optional feature that can be used by
+ * record implementations to provide a typescript
+ * hint for the type of the resource.
+ *
+ * When used, WarpDrive APIs can
+ * take advantage of this to provide better type
+ * safety and intellisense.
+ *
+ * @type {Symbol}
+ */
+const ResourceType = Type;
+
+/**
+ * Symbol for the name of a transform.
+ *
+ * This is an optional feature that can be used by
+ * transform implementations to provide a typescript
+ * hint for the name of the transform.
+ *
+ * If not used, `attr<Transform>('name')` will
+ * allow any string name. `attr('name')` will always
+ * allow any string name.
+ *
+ * If used, `attr<Transform>('name')` will enforce
+ * that the name is the same as the transform name.
+ *
+ * @type {Symbol}
+ */
+const TransformName = Type;
+
+/**
+ * Symbol for use by builders to indicate the return type
+ * generic to use for store.request()
+ *
+ * @type {Symbol}
+ */
+const RequestSignature = getOrSetGlobal('RequestSignature', Symbol('RequestSignature'));
+export { RecordStore, RequestSignature, ResourceType, TransformName, Type };

package/dist/unpkg/dev/utils/string.js

@@ -0,0 +1,91 @@
+const DEFAULT_MAX_CACHE_SIZE = 10_000;
+
+/**
+ * An LRUCache implementation with upsert semantics.
+ *
+ * This implementation is *not* generic, but focuses on
+ * performance tuning for the string transformation cases
+ * where the key maps to the value very simply.
+ *
+ * It takes a work function that should generate a new value
+ * for a given key when called. It will be called when the key
+ * is not found in the cache.
+ *
+ * It keeps track of the number of hits, misses, and ejections
+ * in DEBUG envs, which is useful for tuning the cache size.
+ *
+ * This is an internal utility class for use by this module
+ * and by `@warp-drive/utilities/string`. It is not intended
+ * for use outside of these modules at this time.
+ *
+ * @private
+ */
+class LRUCache {
+  // debug stats
+
+  constructor(doWork, size) {
+    this.size = size || DEFAULT_MAX_CACHE_SIZE;
+    this.state = new Map();
+    this.doWork = doWork;
+    {
+      this._hits = 0;
+      this._misses = 0;
+      this._ejected = 0;
+    }
+  }
+  get(key) {
+    const value = this.state.get(key);
+    if (value) {
+      {
+        this._hits++;
+      }
+      this.state.delete(key);
+      this.state.set(key, value);
+      return value;
+    }
+    {
+      this._misses++;
+    }
+    const newValue = this.doWork(key);
+    this.set(key, newValue);
+    return newValue;
+  }
+  set(key, value) {
+    if (this.state.size === this.size) {
+      for (const [k] of this.state) {
+        {
+          this._ejected++;
+        }
+        this.state.delete(k);
+        break;
+      }
+    }
+    this.state.set(key, value);
+  }
+  clear() {
+    this.state.clear();
+    {
+      this._hits = 0;
+      this._misses = 0;
+      this._ejected = 0;
+    }
+  }
+}
+const STRING_DASHERIZE_REGEXP = /[ _]/g;
+const STRING_DECAMELIZE_REGEXP = /([a-z\d])([A-Z])/g;
+const STRING_DASHERIZE_CACHE = new LRUCache(key => key.replace(STRING_DECAMELIZE_REGEXP, '$1_$2').toLowerCase().replace(STRING_DASHERIZE_REGEXP, '-'));
+
+/**
+ * This is an internal utility function that converts a string
+ * to a dasherized format. Library consumers should use the
+ * re-exported version from `@warp-drive/utilities/string` instead.
+ *
+ * This version is only in this location to support a deprecated
+ * behavior in the core package and will be removed in a future.
+ *
+ * @private
+ */
+function dasherize(str) {
+  return STRING_DASHERIZE_CACHE.get(str);
+}
+export { LRUCache, STRING_DASHERIZE_CACHE, dasherize };