@warp-drive-mirror/utilities 5.7.0-alpha.9 → 5.7.0

package/declarations/-private/active-record/find-record.d.ts

@@ -59,7 +59,7 @@ export type FindRecordResultDocument<T> = Omit<SingleResourceDataDocument<T>, "d
 * @param identifier
 * @param options
 */
-export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions<T>): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
 export declare function findRecord(identifier: RemotelyAccessibleIdentifier, options?: FindRecordOptions): FindRecordRequestOptions;
-export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions<T>): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
 export declare function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;

package/declarations/-private/active-record/query.d.ts

@@ -49,5 +49,5 @@ import type { CollectionResourceDataDocument } from "@warp-drive-mirror/core/typ
 * @param query
 * @param options
 */
-export declare function query<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<CollectionResourceDataDocument<T>, T>;
+export declare function query<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<CollectionResourceDataDocument<T>>;
 export declare function query(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions;

package/declarations/-private/handlers/auto-compress.d.ts

@@ -1,5 +1,11 @@
 import type { Future, Handler, NextFn } from "@warp-drive-mirror/core/request";
 import type { RequestContext } from "@warp-drive-mirror/core/types/request";
+/**
+* Whether the browser supports `ReadableStream` as a request body
+* in a `POST` request.
+*
+* @group Constants
+*/
 export declare const SupportsRequestStreams: boolean;
 interface Constraints {
 	/**
@@ -138,7 +144,7 @@ interface CompressionOptions {
 * }
 * ```
 *
-* @class AutoCompress
+* @group Handlers
 * @public
 * @since 5.5.0
 */

package/declarations/-private/handlers/gated.d.ts

@@ -7,6 +7,7 @@ import type { RequestContext, StructuredDataDocument } from "@warp-drive-mirror/
 type CheckFn = (context: RequestContext) => boolean;
 /**
 *
+* @group Handlers
 * @public
 */
 export declare class Gate implements Handler {

package/declarations/-private/handlers/meta-doc.d.ts

@@ -0,0 +1,47 @@
+import type { Handler } from "@warp-drive-mirror/core/request";
+/**
+* MetaDocHandler processes requests that are marked as meta requests.
+*
+* It treats the response body as "entirely meta" transforming
+*
+* ```ts
+* {
+*   some: "key",
+*   another: "thing"
+* }
+* ```
+*
+* into
+*
+* ```ts
+* {
+* 	 meta: {
+*     some: "key",
+*     another: "thing"
+*   }
+* }
+* ```
+*
+* To activate this handler, a request should specify
+*
+* ```ts
+* options.isMetaRequest = true
+* ```
+*
+* For instance
+*
+* ```ts
+* store.request({
+*   url: '/example',
+*   options: {
+*     isMetaRequest: true
+*   }
+* });
+* ```
+*
+* Errors are not processed by this handler, so if the request fails and the error response
+* is not in {JSON:API} format additional processing may be needed.
+*
+* @group Handlers
+*/
+export declare const MetaDocHandler: Handler;

package/declarations/-private/handlers/utils.d.ts

@@ -2,10 +2,14 @@
 * A unique identifier for the current browser tab
 * useful for observability/tracing and deduping
 * across multiple tabs.
+*
+* @group Constants
 */
 export declare const TAB_ID: string;
 /**
 * The epoch seconds at which the tab id was generated
+*
+* @group Constants
 */
 export declare const TAB_ASSIGNED: number;
 /**
@@ -16,17 +20,22 @@ export declare const TAB_ASSIGNED: number;
 * to enable tracking the browser tab of origin across multiple requests.
 *
 * Follows the template: `Root=1-${now}-${uuidv4};TabId=1-${epochSeconds}-${tab-uuid}`
+*
+* @group Utility Functions
 */
 export declare function addTraceHeader(headers: Headers): Headers;
 /**
 * Source: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html
 * As of 2024-12-05 the maximum URL length is 8192 bytes.
 *
+* @group Constants
 */
 export declare const MAX_URL_LENGTH = 8192;
 /**
 * This assertion takes a URL and throws an error if the URL is longer than the maximum URL length.
 *
 * See also {@link MAX_URL_LENGTH}
+*
+* @group Utility Functions
 */
 export declare function assertInvalidUrlLength(url: string | undefined): void;

package/declarations/-private/json-api/find-record.d.ts

@@ -59,7 +59,7 @@ import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/s
 export type FindRecordResultDocument<T> = Omit<SingleResourceDataDocument<T>, "data"> & {
 	data: T;
 };
-export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions<T>): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
 export declare function findRecord(identifier: RemotelyAccessibleIdentifier, options?: FindRecordOptions): FindRecordRequestOptions;
-export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions<T>): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
 export declare function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;

package/declarations/-private/json-api/query.d.ts

@@ -53,7 +53,7 @@ import type { CollectionResourceDataDocument } from "@warp-drive-mirror/core/typ
 * @param query
 * @param options
 */
-export declare function query<T extends TypedRecordInstance>(type: TypeFromInstance<T>, query?: QueryParamsSource<T>, options?: ConstrainedRequestOptions): QueryRequestOptions<CollectionResourceDataDocument<T>, T>;
+export declare function query<T extends TypedRecordInstance>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<CollectionResourceDataDocument<T>>;
 export declare function query(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions;
 /**
 * Builds request options to query for resources, usually by a primary
@@ -99,5 +99,5 @@ export declare function query(type: string, query?: QueryParamsSource, options?:
 * @param query
 * @param options
 */
-export declare function postQuery<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): PostQueryRequestOptions<CollectionResourceDataDocument<T>, T>;
+export declare function postQuery<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): PostQueryRequestOptions<CollectionResourceDataDocument<T>>;
 export declare function postQuery(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): PostQueryRequestOptions;

package/declarations/-private/json-api/serialize.d.ts

@@ -1,5 +1,5 @@
 import type { Cache } from "@warp-drive-mirror/core/types/cache";
-import type { StableRecordIdentifier } from "@warp-drive-mirror/core/types/identifier";
+import type { ResourceKey } from "@warp-drive-mirror/core/types/identifier";
 import type { Value } from "@warp-drive-mirror/core/types/json/raw";
 import type { InnerRelationshipDocument, ResourceObject } from "@warp-drive-mirror/core/types/spec/json-api-raw";
 type ChangedRelationshipData = InnerRelationshipDocument;
@@ -20,13 +20,13 @@ export type JsonApiResourcePatch = {
 *
 * @public
 * @param {Cache} cache}
-* @param {StableRecordIdentifier} identifier
+* @param {ResourceKey} identifier
 * @return {Object} An object with a `data` property containing the serialized resource patch
 */
-export declare function serializeResources(cache: Cache, identifiers: StableRecordIdentifier): {
+export declare function serializeResources(cache: Cache, identifiers: ResourceKey): {
 	data: ResourceObject;
 };
-export declare function serializeResources(cache: Cache, identifiers: StableRecordIdentifier[]): {
+export declare function serializeResources(cache: Cache, identifiers: ResourceKey[]): {
 	data: ResourceObject[];
 };
 /**
@@ -47,10 +47,10 @@ export declare function serializeResources(cache: Cache, identifiers: StableReco
 *
 * @public
 * @param {Cache} cache}
-* @param {StableRecordIdentifier} identifier
+* @param {ResourceKey} identifier
 * @return {Object} An object with a `data` property containing the serialized resource patch
 */
-export declare function serializePatch(cache: Cache, identifier: StableRecordIdentifier): {
+export declare function serializePatch(cache: Cache, identifier: ResourceKey): {
 	data: JsonApiResourcePatch;
 };
 export {};

package/declarations/-private/rest/find-record.d.ts

@@ -59,7 +59,7 @@ import type { SingleResourceDataDocument } from "@warp-drive-mirror/core/types/s
 export type FindRecordResultDocument<T> = Omit<SingleResourceDataDocument<T>, "data"> & {
 	data: T;
 };
-export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions<T>): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(identifier: RemotelyAccessibleIdentifier<TypeFromInstance<T>>, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
 export declare function findRecord(identifier: RemotelyAccessibleIdentifier, options?: FindRecordOptions): FindRecordRequestOptions;
-export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions<T>): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
+export declare function findRecord<T>(type: TypeFromInstance<T>, id: string, options?: FindRecordOptions): FindRecordRequestOptions<FindRecordResultDocument<T>, T>;
 export declare function findRecord(type: string, id: string, options?: FindRecordOptions): FindRecordRequestOptions;

package/declarations/-private/rest/query.d.ts

@@ -49,5 +49,5 @@ import type { CollectionResourceDataDocument } from "@warp-drive-mirror/core/typ
 * @param query
 * @param options
 */
-export declare function query<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<CollectionResourceDataDocument<T>, T>;
+export declare function query<T>(type: TypeFromInstance<T>, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions<CollectionResourceDataDocument<T>>;
 export declare function query(type: string, query?: QueryParamsSource, options?: ConstrainedRequestOptions): QueryRequestOptions;

package/declarations/handlers.d.ts

@@ -6,4 +6,5 @@
 */
 export { AutoCompress, SupportsRequestStreams } from "./-private/handlers/auto-compress.js";
 export { Gate } from "./-private/handlers/gated.js";
+export { MetaDocHandler } from "./-private/handlers/meta-doc.js";
 export { addTraceHeader, TAB_ASSIGNED, TAB_ID, assertInvalidUrlLength, MAX_URL_LENGTH } from "./-private/handlers/utils.js";

package/declarations/index.d.ts

@@ -1,7 +1,4 @@
 import type { QueryParamsSerializationOptions, QueryParamsSource, Serializable } from "@warp-drive-mirror/core/types/params";
-// prevents the final constructed object from needing to add
-// host and namespace which are provided by the final consuming
-// class to the prototype which can result in overwrite errors
 export interface BuildURLConfig {
 	host: string | null;
 	namespace: string | null;

package/dist/handlers.js

@@ -2,6 +2,13 @@ import { macroCondition, getGlobalConfig } from '@embroider/macros';
 function isCompressibleMethod(method) {
   return method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE';
 }
+
+/**
+ * Whether the browser supports `ReadableStream` as a request body
+ * in a `POST` request.
+ *
+ * @group Constants
+ */
 const SupportsRequestStreams = (() => {
   let duplexAccessed = false;
   const hasContentType = new Request('', {
@@ -54,7 +61,7 @@ const TypedArray = Object.getPrototypeOf(Uint8Array.prototype);
  * }
  * ```
  *
- * @class AutoCompress
+ * @group Handlers
  * @public
  * @since 5.5.0
  */
@@ -154,6 +161,7 @@ function encodingForFormat(format) {
 
 /**
  *
+ * @group Handlers
  * @public
  */
 class Gate {
@@ -168,6 +176,67 @@ class Gate {
     return next(context.request);
   }
 }
+
+/**
+ * MetaDocHandler processes requests that are marked as meta requests.
+ *
+ * It treats the response body as "entirely meta" transforming
+ *
+ * ```ts
+ * {
+ *   some: "key",
+ *   another: "thing"
+ * }
+ * ```
+ *
+ * into
+ *
+ * ```ts
+ * {
+ * 	 meta: {
+ *     some: "key",
+ *     another: "thing"
+ *   }
+ * }
+ * ```
+ *
+ * To activate this handler, a request should specify
+ *
+ * ```ts
+ * options.isMetaRequest = true
+ * ```
+ *
+ * For instance
+ *
+ * ```ts
+ * store.request({
+ *   url: '/example',
+ *   options: {
+ *     isMetaRequest: true
+ *   }
+ * });
+ * ```
+ *
+ * Errors are not processed by this handler, so if the request fails and the error response
+ * is not in {JSON:API} format additional processing may be needed.
+ *
+ * @group Handlers
+ */
+const MetaDocHandler = {
+  request(context, next) {
+    if (!context.request.options?.isMetaRequest) {
+      return next(context.request);
+    }
+    return next(context.request).then(response => {
+      return processResponse(response);
+    });
+  }
+};
+function processResponse(response) {
+  return {
+    meta: response.content
+  };
+}
 if (typeof FastBoot === 'undefined') {
   globalThis.addEventListener('beforeunload', function () {
     sessionStorage.setItem('tab-closed', 'true');
@@ -195,10 +264,14 @@ function getTabId() {
  * A unique identifier for the current browser tab
  * useful for observability/tracing and deduping
  * across multiple tabs.
+ *
+ * @group Constants
  */
 const TAB_ID = getTabId();
 /**
  * The epoch seconds at which the tab id was generated
+ *
+ * @group Constants
  */
 const TAB_ASSIGNED = Math.floor(Date.now() / 1000);
 
@@ -210,6 +283,8 @@ const TAB_ASSIGNED = Math.floor(Date.now() / 1000);
  * to enable tracking the browser tab of origin across multiple requests.
  *
  * Follows the template: `Root=1-${now}-${uuidv4};TabId=1-${epochSeconds}-${tab-uuid}`
+ *
+ * @group Utility Functions
  */
 function addTraceHeader(headers) {
   const now = Math.floor(Date.now() / 1000);
@@ -221,6 +296,7 @@ function addTraceHeader(headers) {
  * Source: https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cloudfront-limits.html
  * As of 2024-12-05 the maximum URL length is 8192 bytes.
  *
+ * @group Constants
  */
 const MAX_URL_LENGTH = 8192;
 
@@ -228,6 +304,8 @@ const MAX_URL_LENGTH = 8192;
  * This assertion takes a URL and throws an error if the URL is longer than the maximum URL length.
  *
  * See also {@link MAX_URL_LENGTH}
+ *
+ * @group Utility Functions
  */
 function assertInvalidUrlLength(url) {
   macroCondition(getGlobalConfig().WarpDriveMirror.env.DEBUG) ? (test => {
@@ -236,4 +314,4 @@ function assertInvalidUrlLength(url) {
     }
   })(!url || url.length <= MAX_URL_LENGTH) : {};
 }
-export { AutoCompress, Gate, MAX_URL_LENGTH, SupportsRequestStreams, TAB_ASSIGNED, TAB_ID, addTraceHeader, assertInvalidUrlLength };
+export { AutoCompress, Gate, MAX_URL_LENGTH, MetaDocHandler, SupportsRequestStreams, TAB_ASSIGNED, TAB_ID, addTraceHeader, assertInvalidUrlLength };

package/dist/json-api.js

@@ -538,7 +538,7 @@ function updateRecord(record, options = {}) {
  *
  * @public
  * @param {Cache} cache}
- * @param {StableRecordIdentifier} identifier
+ * @param {ResourceKey} identifier
  * @return {Object} An object with a `data` property containing the serialized resource patch
  */
 function serializeResources(cache, identifiers) {
@@ -623,7 +623,7 @@ function _serializeResource(cache, identifier) {
  *
  * @public
  * @param {Cache} cache}
- * @param {StableRecordIdentifier} identifier
+ * @param {ResourceKey} identifier
  * @return {Object} An object with a `data` property containing the serialized resource patch
  */
 function serializePatch(cache, identifier) {

package/dist/string.cjs

@@ -22,7 +22,7 @@ const DEFAULT_MAX_CACHE_SIZE = 10_000;
  * and by `@warp-drive-mirror/utilities/string`. It is not intended
  * for use outside of these modules at this time.
  *
- * @internal
+ * @private
  */
 class LRUCache {
   // debug stats
@@ -68,7 +68,7 @@ const STRING_DASHERIZE_CACHE = new LRUCache(key => key.replace(STRING_DECAMELIZE
  * This version is only in this location to support a deprecated
  * behavior in the core package and will be removed in a future.
  *
- * @internal
+ * @private
  */
 function dasherize$1(str) {
   return STRING_DASHERIZE_CACHE.get(str);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive-mirror/utilities",
-  "version": "5.7.0-alpha.9",
+  "version": "5.7.0",
   "description": "Utilities package for WarpDrive | Things your app might find useful",
   "keywords": [
     "ember-addon"
@@ -36,21 +36,21 @@
     }
   },
   "peerDependencies": {
-    "@warp-drive-mirror/core": "5.7.0-alpha.9"
+    "@warp-drive-mirror/core": "5.7.0"
   },
   "dependencies": {
-    "@embroider/macros": "^1.16.12"
+    "@embroider/macros": "^1.18.1"
   },
   "devDependencies": {
-    "@babel/core": "^7.26.10",
-    "@babel/plugin-transform-typescript": "^7.27.0",
-    "@babel/preset-typescript": "^7.27.0",
-    "@warp-drive/internal-config": "5.7.0-alpha.9",
-    "@warp-drive-mirror/core": "5.7.0-alpha.9",
+    "@babel/core": "^7.28.3",
+    "@babel/plugin-transform-typescript": "^7.28.0",
+    "@babel/preset-typescript": "^7.27.1",
+    "@warp-drive/internal-config": "5.7.0",
+    "@warp-drive-mirror/core": "5.7.0",
     "decorator-transforms": "^2.3.0",
-    "expect-type": "^1.2.1",
-    "typescript": "^5.8.3",
-    "vite": "^7.0.0"
+    "expect-type": "^1.2.2",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.3"
   },
   "volta": {
     "extends": "../../../../../../package.json"