@warp-drive-mirror/utilities 5.7.0-alpha.24 → 5.7.0-alpha.25

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warp-drive-mirror/utilities",
-  "version": "5.7.0-alpha.24",
+  "version": "5.7.0-alpha.25",
   "description": "Utilities package for WarpDrive | Things your app might find useful",
   "keywords": [
     "ember-addon"
@@ -36,7 +36,7 @@
     }
   },
   "peerDependencies": {
-    "@warp-drive-mirror/core": "5.7.0-alpha.24"
+    "@warp-drive-mirror/core": "5.7.0-alpha.25"
   },
   "dependencies": {
     "@embroider/macros": "^1.16.12"
@@ -45,8 +45,8 @@
     "@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.24",
-    "@warp-drive-mirror/core": "5.7.0-alpha.24",
+    "@warp-drive/internal-config": "5.7.0-alpha.25",
+    "@warp-drive-mirror/core": "5.7.0-alpha.25",
     "decorator-transforms": "^2.3.0",
     "expect-type": "^1.2.1",
     "typescript": "^5.8.3",