@warp-drive-mirror/utilities 5.8.0-beta.0 → 5.8.0-beta.2

package/dist/unpkg/dev-deprecated/handlers.js

@@ -0,0 +1,316 @@
+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('', {
+    body: new ReadableStream(),
+    method: 'POST',
+    // @ts-expect-error untyped
+    get duplex() {
+      duplexAccessed = true;
+      return 'half';
+    }
+  }).headers.has('Content-Type');
+  return duplexAccessed && !hasContentType;
+})();
+
+/**
+ * Options for configuring the AutoCompress handler.
+ *
+ */
+
+const DEFAULT_CONSTRAINTS = {
+  Blob: 1000,
+  ArrayBuffer: 1000,
+  TypedArray: 1000,
+  DataView: 1000,
+  String: 1000
+};
+const TypedArray = Object.getPrototypeOf(Uint8Array);
+
+/**
+ * A request handler that automatically compresses the request body
+ * if the request body is a string, array buffer, blob, or form data.
+ *
+ * This uses the [CompressionStream API](https://developer.mozilla.org/en-US/docs/Web/API/CompressionStream)
+ *
+ * The compression format as well as the kinds of data to compress can be
+ * configured using the `format` and `constraints` options.
+ *
+ * ```diff
+ * +import { AutoCompress } from '@ember-data-mirror/request-utils/handlers';
+ * import Fetch from '@ember-data-mirror/request/fetch';
+ * import RequestManager from '@ember-data-mirror/request';
+ * import Store from '@ember-data-mirror/store';
+ *
+ * class AppStore extends Store {
+ *   requestManager = new RequestManager()
+ *     .use([
+ * +       new AutoCompress(),
+ *        Fetch
+ *     ]);
+ * }
+ * ```
+ *
+ * @group Handlers
+ * @public
+ * @since 5.5.0
+ */
+class AutoCompress {
+  constructor(options = {}) {
+    const opts = {
+      format: options.format ?? 'gzip',
+      constraints: Object.assign({}, DEFAULT_CONSTRAINTS, options.constraints),
+      allowStreaming: options.allowStreaming ?? false,
+      forceStreaming: options.forceStreaming ?? false
+    };
+    this.options = opts;
+  }
+  request({
+    request
+  }, next) {
+    const {
+      constraints
+    } = this.options;
+    const {
+      body
+    } = request;
+    const shouldCompress = !!body && isCompressibleMethod(request.method) && request.options?.compress !== false && (
+    // prettier-ignore
+    request.options?.compress ? true : typeof body === 'string' || body instanceof String ? canCompress('String', constraints, body.length) : body instanceof Blob ? canCompress('Blob', constraints, body.size) : body instanceof ArrayBuffer ? canCompress('ArrayBuffer', constraints, body.byteLength) : body instanceof DataView ? canCompress('DataView', constraints, body.byteLength) : body instanceof TypedArray ? canCompress('TypedArray', constraints, body.byteLength) : false);
+    if (!shouldCompress) return next(request);
+
+    // A convenient way to convert all of the supported body types to a readable
+    // stream is to use a `Response` object body
+    const response = new Response(request.body);
+    const stream = response.body?.pipeThrough(new CompressionStream(this.options.format));
+    const headers = new Headers(request.headers);
+    headers.set('Content-Encoding', encodingForFormat(this.options.format));
+
+    //
+    // For browsers that support it, `fetch` can receive a `ReadableStream` as
+    // the body, so all we need to do is to create a new `ReadableStream` and
+    // compress it on the fly
+    //
+    const forceStreaming = request.options?.forceStreaming ?? this.options.forceStreaming;
+    const allowStreaming = request.options?.allowStreaming ?? this.options.allowStreaming;
+    if (forceStreaming || SupportsRequestStreams && allowStreaming) {
+      const req = Object.assign({}, request, {
+        body: stream,
+        headers
+      });
+      if (SupportsRequestStreams) {
+        // @ts-expect-error untyped
+        req.duplex = 'half';
+      }
+      return next(req);
+
+      //
+      // For non-chromium browsers, we have to "pull" the stream to get the final
+      // bytes and supply the final byte array as the new request body.
+      //
+    }
+
+    // we need to pull the stream to get the final bytes
+    const resp = new Response(stream);
+    return resp.blob().then(blob => {
+      const req = Object.assign({}, request, {
+        body: blob,
+        headers
+      });
+      return next(req);
+    });
+  }
+}
+function canCompress(type, constraints, size) {
+  // if we have a value of 0, we can compress anything
+  if (constraints[type] === 0) return true;
+  if (constraints[type] === -1) return false;
+  return size >= constraints[type];
+}
+function encodingForFormat(format) {
+  switch (format) {
+    case 'gzip':
+    case 'deflate':
+    case 'deflate-raw':
+      return format;
+    default:
+      (test => {
+        {
+          throw new Error(`Unsupported compression format: ${format}`);
+        }
+      })();
+      // @ts-expect-error - unreachable code is reachable in production
+      return format;
+  }
+}
+
+/**
+ * If CheckFn returns true, the wrapped handler will be used.
+ * If CheckFn returns false, the wrapped handler will be skipped.
+ */
+
+/**
+ *
+ * @group Handlers
+ * @public
+ */
+class Gate {
+  constructor(handler, checkFn) {
+    this.handler = handler;
+    this.checkFn = checkFn;
+  }
+  request(context, next) {
+    if (this.checkFn(context)) {
+      return this.handler.request(context, next);
+    }
+    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');
+  });
+}
+function getTabId() {
+  if (typeof sessionStorage === 'undefined') {
+    return crypto.randomUUID();
+  }
+  const tabId = sessionStorage.getItem('tab-id');
+  if (tabId) {
+    const tabClosed = sessionStorage.getItem('tab-closed');
+    if (tabClosed === 'true') {
+      return tabId;
+    }
+
+    // fall through to generate a new tab id
+  }
+  const newTabId = crypto.randomUUID();
+  sessionStorage.setItem('tab-id', newTabId);
+  return newTabId;
+}
+
+/**
+ * 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);
+
+/**
+ * Adds the `X-Amzn-Trace-Id` header to support observability
+ * tooling around request routing.
+ *
+ * This makes use of the {@link TAB_ID} and {@link TAB_ASSIGNED}
+ * 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);
+  headers.set('X-Amzn-Trace-Id', `Root=1-${now}-${crypto.randomUUID()};TabId=1-${TAB_ASSIGNED}-${TAB_ID}`);
+  return 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;
+
+/**
+ * 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) {
+  (test => {
+    if (!test) {
+      throw new Error(`URL length ${url?.length} exceeds the maximum URL length of ${MAX_URL_LENGTH} bytes.\n\nConsider converting this request query a \`/query\` endpoint instead of a GET, or upgrade the current endpoint to be able to receive a POST request directly (ideally specifying the header HTTP-Method-Override: QUERY)\n\nThe Invalid URL is:\n\n${url}`);
+    }
+  })(!url || url.length <= MAX_URL_LENGTH);
+}
+export { AutoCompress, Gate, MAX_URL_LENGTH, MetaDocHandler, SupportsRequestStreams, TAB_ASSIGNED, TAB_ID, addTraceHeader, assertInvalidUrlLength };

package/dist/unpkg/dev-deprecated/index.js

@@ -0,0 +1,362 @@
+import { getOrSetGlobal } from '@warp-drive-mirror/core/types/-private';
+
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+
+// 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
+
+const CONFIG = getOrSetGlobal('CONFIG', {
+  host: '',
+  namespace: ''
+});
+
+/**
+ * Sets the global configuration for `buildBaseURL`
+ * for host and namespace values for the application.
+ *
+ * These values may still be overridden by passing
+ * them to buildBaseURL directly.
+ *
+ * This method may be called as many times as needed.
+ * host values of `''` or `'/'` are equivalent.
+ *
+ * Except for the value of `/` as host, host should not
+ * end with `/`.
+ *
+ * namespace should not start or end with a `/`.
+ *
+ * ```ts
+ * type BuildURLConfig = {
+ *   host: string;
+ *   namespace: string'
+ * }
+ * ```
+ *
+ * Example:
+ *
+ * ```ts
+ * import { setBuildURLConfig } from '@ember-data-mirror/request-utils';
+ *
+ * setBuildURLConfig({
+ *   host: 'https://api.example.com',
+ *   namespace: 'api/v1'
+ * });
+ * ```
+ *
+ * @public
+ */
+function setBuildURLConfig(config) {
+  (test => {
+    if (!test) {
+      throw new Error(`setBuildURLConfig: You must pass a config object`);
+    }
+  })(config);
+  (test => {
+    if (!test) {
+      throw new Error(`setBuildURLConfig: You must pass a config object with a 'host' or 'namespace' property`);
+    }
+  })('host' in config || 'namespace' in config);
+  CONFIG.host = config.host || '';
+  CONFIG.namespace = config.namespace || '';
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: host must NOT end with '/', received '${CONFIG.host}'`);
+    }
+  })(CONFIG.host === '/' || !CONFIG.host.endsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: namespace must NOT start with '/', received '${CONFIG.namespace}'`);
+    }
+  })(!CONFIG.namespace.startsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: namespace must NOT end with '/', received '${CONFIG.namespace}'`);
+    }
+  })(!CONFIG.namespace.endsWith('/'));
+}
+const OPERATIONS_WITH_PRIMARY_RECORDS = new Set(['findRecord', 'findRelatedRecord', 'findRelatedCollection', 'updateRecord', 'deleteRecord']);
+function isOperationWithPrimaryRecord(options) {
+  return 'op' in options && OPERATIONS_WITH_PRIMARY_RECORDS.has(options.op);
+}
+function hasResourcePath(options) {
+  return 'resourcePath' in options && typeof options.resourcePath === 'string' && options.resourcePath.length > 0;
+}
+function resourcePathForType(options) {
+  (test => {
+    if (!test) {
+      throw new Error(`resourcePathForType: You must pass a valid op as part of options`);
+    }
+  })('op' in options && typeof options.op === 'string');
+  return options.op === 'findMany' ? options.identifiers[0].type : options.identifier.type;
+}
+
+/**
+ * Builds a URL for a request based on the provided options.
+ * Does not include support for building query params (see `buildQueryParams`)
+ * so that it may be composed cleanly with other query-params strategies.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import { buildBaseURL } from '@ember-data-mirror/request-utils';
+ *
+ * const url = buildBaseURL({
+ *   host: 'https://api.example.com',
+ *   namespace: 'api/v1',
+ *   resourcePath: 'emberDevelopers',
+ *   op: 'query',
+ *   identifier: { type: 'ember-developer' }
+ * });
+ *
+ * // => 'https://api.example.com/api/v1/emberDevelopers'
+ * ```
+ *
+ * On the surface this may seem like a lot of work to do something simple, but
+ * it is designed to be composable with other utilities and interfaces that the
+ * average product engineer will never need to see or use.
+ *
+ * A few notes:
+ *
+ * - `resourcePath` is optional, but if it is not provided, `identifier.type` will be used.
+ * - `host` and `namespace` are optional, but if they are not provided, the values globally
+ *    configured via `setBuildURLConfig` will be used.
+ * - `op` is required and must be one of the following:
+ *   - 'findRecord' 'query' 'findMany' 'findRelatedCollection' 'findRelatedRecord'` 'createRecord' 'updateRecord' 'deleteRecord'
+ * - Depending on the value of `op`, `identifier` or `identifiers` will be required.
+ *
+ * @public
+ */
+function buildBaseURL(urlOptions) {
+  const options = Object.assign({
+    host: CONFIG.host,
+    namespace: CONFIG.namespace
+  }, urlOptions);
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: You must pass \`op\` as part of options`);
+    }
+  })(hasResourcePath(options) || typeof options.op === 'string' && options.op.length > 0);
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: You must pass \`identifier\` as part of options`);
+    }
+  })(hasResourcePath(options) || options.op === 'findMany' || options.identifier && typeof options.identifier === 'object');
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: You must pass \`identifiers\` as part of options`);
+    }
+  })(hasResourcePath(options) || options.op !== 'findMany' || options.identifiers && Array.isArray(options.identifiers) && options.identifiers.length > 0 && options.identifiers.every(i => i && typeof i === 'object'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: You must pass valid \`identifier\` as part of options, expected 'id'`);
+    }
+  })(hasResourcePath(options) || !isOperationWithPrimaryRecord(options) || typeof options.identifier.id === 'string' && options.identifier.id.length > 0);
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: You must pass \`identifiers\` as part of options`);
+    }
+  })(hasResourcePath(options) || options.op !== 'findMany' || options.identifiers.every(i => typeof i.id === 'string' && i.id.length > 0));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: You must pass valid \`identifier\` as part of options, expected 'type'`);
+    }
+  })(hasResourcePath(options) || options.op === 'findMany' || typeof options.identifier.type === 'string' && options.identifier.type.length > 0);
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: You must pass valid \`identifiers\` as part of options, expected 'type'`);
+    }
+  })(hasResourcePath(options) || options.op !== 'findMany' || typeof options.identifiers[0].type === 'string' && options.identifiers[0].type.length > 0);
+
+  // prettier-ignore
+  const idPath = isOperationWithPrimaryRecord(options) ? encodeURIComponent(options.identifier.id) : '';
+  const resourcePath = options.resourcePath || resourcePathForType(options);
+  const {
+    host,
+    namespace
+  } = options;
+  const fieldPath = 'fieldPath' in options ? options.fieldPath : '';
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: You tried to build a url for a ${String('op' in options ? options.op + ' ' : '')}request to ${resourcePath} but resourcePath must be set or op must be one of "${['findRecord', 'findRelatedRecord', 'findRelatedCollection', 'updateRecord', 'deleteRecord', 'createRecord', 'query', 'findMany'].join('","')}".`);
+    }
+  })(hasResourcePath(options) || ['findRecord', 'query', 'findMany', 'findRelatedCollection', 'findRelatedRecord', 'createRecord', 'updateRecord', 'deleteRecord'].includes(options.op));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: host must NOT end with '/', received '${host}'`);
+    }
+  })(host === '/' || !host.endsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: namespace must NOT start with '/', received '${namespace}'`);
+    }
+  })(!namespace.startsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: namespace must NOT end with '/', received '${namespace}'`);
+    }
+  })(!namespace.endsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: resourcePath must NOT start with '/', received '${resourcePath}'`);
+    }
+  })(!resourcePath.startsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: resourcePath must NOT end with '/', received '${resourcePath}'`);
+    }
+  })(!resourcePath.endsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: fieldPath must NOT start with '/', received '${fieldPath}'`);
+    }
+  })(!fieldPath.startsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: fieldPath must NOT end with '/', received '${fieldPath}'`);
+    }
+  })(!fieldPath.endsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: idPath must NOT start with '/', received '${idPath}'`);
+    }
+  })(!idPath.startsWith('/'));
+  (test => {
+    if (!test) {
+      throw new Error(`buildBaseURL: idPath must NOT end with '/', received '${idPath}'`);
+    }
+  })(!idPath.endsWith('/'));
+  const hasHost = host !== '' && host !== '/';
+  const url = [hasHost ? host : '', namespace, resourcePath, idPath, fieldPath].filter(Boolean).join('/');
+  return hasHost ? url : `/${url}`;
+}
+const DEFAULT_QUERY_PARAMS_SERIALIZATION_OPTIONS = {
+  arrayFormat: 'comma'
+};
+function handleInclude(include) {
+  (test => {
+    if (!test) {
+      throw new Error(`Expected include to be a string or array, got ${typeof include}`);
+    }
+  })(typeof include === 'string' || Array.isArray(include));
+  return typeof include === 'string' ? include.split(',') : include;
+}
+
+/**
+ * filter out keys of an object that have falsy values or point to empty arrays
+ * returning a new object with only those keys that have truthy values / non-empty arrays
+ *
+ * @public
+ * @param source object to filter keys with empty values from
+ * @return A new object with the keys that contained empty values removed
+ */
+function filterEmpty(source) {
+  const result = {};
+  for (const key in source) {
+    const value = source[key];
+    // Allow `0` and `false` but filter falsy values that indicate "empty"
+    if (value !== undefined && value !== null && value !== '') {
+      if (!Array.isArray(value) || value.length > 0) {
+        result[key] = source[key];
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Sorts query params by both key and value returning a new URLSearchParams
+ * object with the keys inserted in sorted order.
+ *
+ * Treats `included` specially, splicing it into an array if it is a string and sorting the array.
+ *
+ * Options:
+ * - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'
+ *
+ * 'bracket': appends [] to the key for every value e.g. `&ids[]=1&ids[]=2`
+ * 'indices': appends [i] to the key for every value e.g. `&ids[0]=1&ids[1]=2`
+ * 'repeat': appends the key for every value e.g. `&ids=1&ids=2`
+ * 'comma' (default): appends the key once with a comma separated list of values e.g. `&ids=1,2`
+ *
+ * @public
+ * @return A {@link URLSearchParams} with keys inserted in sorted order
+ */
+function sortQueryParams(params, options) {
+  const opts = Object.assign({}, DEFAULT_QUERY_PARAMS_SERIALIZATION_OPTIONS, options);
+  const paramsIsObject = !(params instanceof URLSearchParams);
+  const urlParams = new URLSearchParams();
+  const dictionaryParams = paramsIsObject ? params : {};
+  if (!paramsIsObject) {
+    params.forEach((value, key) => {
+      const hasExisting = key in dictionaryParams;
+      if (!hasExisting) {
+        dictionaryParams[key] = value;
+      } else {
+        const existingValue = dictionaryParams[key];
+        if (Array.isArray(existingValue)) {
+          existingValue.push(value);
+        } else {
+          dictionaryParams[key] = [existingValue, value];
+        }
+      }
+    });
+  }
+  if ('include' in dictionaryParams) {
+    dictionaryParams.include = handleInclude(dictionaryParams.include);
+  }
+  const sortedKeys = Object.keys(dictionaryParams).sort();
+  sortedKeys.forEach(key => {
+    const value = dictionaryParams[key];
+    if (Array.isArray(value)) {
+      value.sort();
+      switch (opts.arrayFormat) {
+        case 'indices':
+          value.forEach((v, i) => {
+            urlParams.append(`${key}[${i}]`, String(v));
+          });
+          return;
+        case 'bracket':
+          value.forEach(v => {
+            urlParams.append(`${key}[]`, String(v));
+          });
+          return;
+        case 'repeat':
+          value.forEach(v => {
+            urlParams.append(key, String(v));
+          });
+          return;
+        case 'comma':
+        default:
+          urlParams.append(key, value.join(','));
+          return;
+      }
+    } else {
+      urlParams.append(key, String(value));
+    }
+  });
+  return urlParams;
+}
+
+/**
+ * Sorts query params by both key and value, returning a query params string
+ *
+ * Treats `included` specially, splicing it into an array if it is a string and sorting the array.
+ *
+ * Options:
+ * - arrayFormat: 'bracket' | 'indices' | 'repeat' | 'comma'
+ *
+ * 'bracket': appends [] to the key for every value e.g. `ids[]=1&ids[]=2`
+ * 'indices': appends [i] to the key for every value e.g. `ids[0]=1&ids[1]=2`
+ * 'repeat': appends the key for every value e.g. `ids=1&ids=2`
+ * 'comma' (default): appends the key once with a comma separated list of values e.g. `ids=1,2`
+ *
+ * @public
+ * @return A sorted query params string without the leading `?`
+ */
+function buildQueryParams(params, options) {
+  return sortQueryParams(params, options).toString();
+}
+export { buildBaseURL, buildQueryParams, filterEmpty, setBuildURLConfig, sortQueryParams };