@warp-drive/core 5.6.0-alpha.11

package/declarations/request/-private/types.d.ts

@@ -0,0 +1,236 @@
+import type { StableDocumentIdentifier } from '../../types/identifier';
+import type { IS_FUTURE, RequestContext, RequestInfo, ResponseInfo, StructuredDataDocument } from '../../types/request';
+export interface GodContext {
+    controller: AbortController;
+    response: ResponseInfo | null;
+    stream: ReadableStream | Promise<ReadableStream | null> | null;
+    hasRequestedStream: boolean;
+    id: number;
+    identifier: StableDocumentIdentifier | null;
+}
+export type Deferred<T> = {
+    resolve(v: T): void;
+    reject(v: unknown): void;
+    promise: Promise<T>;
+};
+export type ManagedRequestPriority = {
+    blocking: boolean;
+};
+export type DeferredStream = {
+    resolve(v: ReadableStream | null): void;
+    reject(v: unknown): void;
+    promise: Promise<ReadableStream | null> & {
+        sizeHint?: number;
+    };
+};
+/**
+ * A Future is a {@link Promise} which resolves to a {@link StructuredDataDocument | StructuredDocument}
+ * while providing the ability to {@link Future.abort | abort} the underlying request, and
+ * {@link Future.getStream | access the response stream} before the outer promise resolves;
+ *
+ * @public
+ */
+export interface Future<T> extends Promise<StructuredDataDocument<T>> {
+    [IS_FUTURE]: true;
+    /**
+     * Cancel this request by firing the {@link AbortController}'s signal.
+     *
+     * @privateRemarks
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/abort)
+     *
+     * @param reason optional reason for aborting the request
+     * @public
+     */
+    abort(reason?: string): void;
+    /**
+     * Get the response stream, if any, once made available.
+     *
+     * @public
+     * @return {Promise<ReadableStream | null>}
+     */
+    getStream(): Promise<ReadableStream | null>;
+    /**
+     *  Run a callback when this request completes. Use sparingly,
+     *  mostly useful for instrumentation and infrastructure.
+     *
+     * @param cb the callback to run
+     * @public
+     * @return {void}
+     */
+    onFinalize(cb: () => void): void;
+    /**
+     * The identifier of the associated request, if any, as
+     * assigned by the CacheHandler.
+     *
+     * @property lid
+     * @type {StableDocumentIdentifier | null}
+     * @public
+     */
+    lid: StableDocumentIdentifier | null;
+    /**
+     * The id of the associated request, if any, as assigned
+     * by the RequestManager
+     *
+     * @property id
+     * @type {Number}
+     * @public
+     */
+    id: number;
+}
+export type DeferredFuture<T> = {
+    resolve(v: StructuredDataDocument<T>): void;
+    reject(v: unknown): void;
+    promise: Future<T>;
+};
+export type NextFn<P = unknown> = (req: RequestInfo) => Future<P>;
+/**
+ * Requests are fulfilled by handlers. A handler receives the request context
+as well as a `next` function with which to pass along a request to the next
+handler if it so chooses.
+
+A handler may be any object with a `request` method. This allows both stateful and non-stateful
+handlers to be utilized.
+
+If a handler calls `next`, it receives a `Future` which resolves to a `StructuredDocument`
+that it can then compose how it sees fit with its own response.
+
+```ts
+type NextFn<P> = (req: RequestInfo) => Future<P>;
+
+interface Handler {
+  async request<T>(context: RequestContext, next: NextFn<P>): T;
+}
+```
+
+`RequestContext` contains a readonly version of the RequestInfo as well as a few methods for building up the `StructuredDocument` and `Future` that will be part of the response.
+
+```ts
+interface RequestContext<T> {
+  readonly request: RequestInfo;
+
+  setStream(stream: ReadableStream | Promise<ReadableStream>): void;
+  setResponse(response: Response | ResponseInfo): void;
+}
+```
+
+A basic `fetch` handler with support for streaming content updates while
+the download is still underway might look like the following, where we use
+[`response.clone()`](https://developer.mozilla.org/en-US/docs/Web/API/Response/clone) to `tee` the `ReadableStream` into two streams.
+
+A more efficient handler might read from the response stream, building up the
+response content before passing along the chunk downstream.
+
+```ts
+const FetchHandler = {
+  async request(context) {
+    const response = await fetch(context.request);
+    context.setResponse(reponse);
+    context.setStream(response.clone().body);
+
+    return response.json();
+  }
+}
+```
+
+### Stream Currying
+
+`RequestManager.request` and `next` differ from `fetch` in one **crucial detail** in that the outer Promise resolves only once the response stream has been processed.
+
+For context, it helps to understand a few of the use-cases that RequestManager
+is intended to allow.
+
+ - to manage and return streaming content (such as video files)
+ - to fulfill a request from multiple sources or by splitting one request into multiple requests
+   - for instance one API call for a user and another for the user's friends
+   - or e.g. fulfilling part of the request from one source (one API, in-memory, localStorage, IndexedDB etc.) and the rest from another source (a different API, a WebWorker, etc.)
+ - to coalesce multiple requests
+ - to decorate a request with additional info
+   - e.g. an Auth handler that ensures the correct tokens or headers or cookies are attached.
+
+----
+
+`await fetch(<req>)` resolves at the moment headers are received. This allows for the body of the request to be processed as a stream by application
+code *while chunks are still being received by the browser*.
+
+When an app chooses to `await response.json()` what occurs is the browser reads the stream to completion and then returns the result. Additionally, this stream may only be read **once**.
+
+The `RequestManager` preserves this ability to subscribe to and utilize the stream by either the application or the handler – thereby delivering the full power and flexibility of native APIs – without restricting developers in ways that lead to complicated workarounds.
+
+Each handler may call `setStream` only once, but may do so *at any time* until the promise that the handler returns has resolved. The associated promise returned by calling `future.getStream` will resolve with the stream set by `setStream` if that method is called, or `null` if that method
+has not been called by the time that the handler's request method has resolved.
+
+Handlers that do not create a stream of their own, but which call `next`, should defensively pipe the stream forward. While this is not required (see automatic currying below) it is better to do so in most cases as otherwise the stream may not become available to downstream handlers or the application until the upstream handler has fully read it.
+
+```ts
+context.setStream(future.getStream());
+```
+
+Handlers that either call `next` multiple times or otherwise have reason to create multiple  fetch requests should either choose to return no stream, meaningfully combine the streams, or select a single prioritized stream.
+
+Of course, any handler may choose to read and handle the stream, and return either no stream or a different stream in the process.
+
+### Automatic Currying of Stream and Response
+
+In order to simplify the common case for handlers which decorate a request, if `next` is called only a single time and `setResponse` was never called by the handler, the response set by the next handler in the chain will be applied to that handler's outcome. For instance, this makes the following pattern possible `return (await next(<req>)).content;`.
+
+Similarly, if `next` is called only a single time and neither `setStream` nor `getStream` was called, we automatically curry the stream from the future returned by `next` onto the future returned by the handler.
+
+Finally, if the return value of a handler is a `Future`, we curry `content` and `errors` as well, thus enabling the simplest form `return next(<req>)`.
+
+In the case of the `Future` being returned, `Stream` proxying is automatic and immediate and does not wait for the `Future` to resolve.
+
+### Handler Order
+
+Request handlers are registered by configuring the manager via `use`
+
+```ts
+const manager = new RequestManager()
+  .use([Handler1, Handler2]);
+```
+
+Handlers will be invoked in the order they are registered ("fifo", first-in first-out), and may only be registered up until the first request is made. It is recommended but not required to register all handlers at one time in order to ensure explicitly visible handler ordering.
+
+
+ @class (Interface) Handler
+ @public
+*/
+export interface Handler {
+    /**
+     * Method to implement to handle requests. Receives the request
+     * context and a nextFn to call to pass-along the request to
+     * other handlers.
+     *
+     * @public
+     * @param context
+     * @param next
+     */
+    request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T>;
+}
+/**
+ * The CacheHandler is identical to other handlers ecxept that it
+ * is allowed to return a value synchronously. This is useful for
+ * features like reducing microtask queueing when de-duping.
+ *
+ * A RequestManager may only have one CacheHandler, registered via
+ * `manager.useCache(CacheHandler)`.
+ *
+ * @class (Interface) CacheHandler
+ * @public
+ */
+export interface CacheHandler {
+    /**
+     * Method to implement to handle requests. Receives the request
+     * context and a nextFn to call to pass-along the request to
+     * other handlers.
+     *
+     * @public
+     * @param context
+     * @param next
+     */
+    request<T = unknown>(context: RequestContext, next: NextFn<T>): Promise<T | StructuredDataDocument<T>> | Future<T> | T;
+}
+export interface RequestResponse<T> {
+    result: T;
+}
+export type GenericCreateArgs = Record<string | symbol, unknown>;
+//# sourceMappingURL=types.d.ts.map

package/declarations/request/-private/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/request/-private/types.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,16 @@
+import type { RequestInfo, StructuredDataDocument } from '../../types/request';
+import { ContextOwner } from './context';
+import type { DeferredFuture, Future, GodContext, Handler } from './types';
+export declare const IS_CACHE_HANDLER: "___(unique) Symbol(IS_CACHE_HANDLER)";
+export declare function curryFuture<T>(owner: ContextOwner, inbound: Future<T>, outbound: DeferredFuture<T>): Future<T>;
+export interface HttpErrorProps extends DOMException {
+    code: number;
+    name: string;
+    status: number;
+    statusText: string;
+    isRequestError: boolean;
+}
+export declare function enhanceReason(reason?: string): DOMException;
+export declare function handleOutcome<T>(owner: ContextOwner, inbound: Promise<T | StructuredDataDocument<T>>, outbound: DeferredFuture<T>): Future<T>;
+export declare function executeNextHandler<T>(wares: Readonly<Handler[]>, request: RequestInfo, i: number, god: GodContext): Future<T>;
+//# sourceMappingURL=utils.d.ts.map

package/declarations/request/-private/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/request/-private/utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,WAAW,EACX,sBAAsB,EAGvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAW,YAAY,EAAE,MAAM,WAAW,CAAC;AAIlD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAE3E,eAAO,MAAM,gBAAgB,wCAAiE,CAAC;AAC/F,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAuC9G;AA4BD,MAAM,WAAW,cAAe,SAAQ,YAAY;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAE3D;AAED,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,OAAO,CAAC,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC,EAC/C,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,GAC1B,MAAM,CAAC,CAAC,CAAC,CA6CX;AAMD,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,KAAK,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,EAC1B,OAAO,EAAE,WAAW,EACpB,CAAC,EAAE,MAAM,EACT,GAAG,EAAE,UAAU,GACd,MAAM,CAAC,CAAC,CAAC,CAmDX"}

package/declarations/request.d.ts

@@ -0,0 +1,6 @@
+export { createDeferred } from './request/-private/future.ts';
+export type { Future, Handler, CacheHandler, NextFn, Deferred, ManagedRequestPriority, } from './request/-private/types.ts';
+export { setPromiseResult, getPromiseResult } from './request/-private/promise-cache.ts';
+export type { Awaitable } from './request/-private/promise-cache.ts';
+export type { Context } from './request/-private/context.ts';
+//# sourceMappingURL=request.d.ts.map

package/declarations/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../src/request.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EACV,MAAM,EACN,OAAO,EACP,YAAY,EACZ,MAAM,EACN,QAAQ,EACR,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACzF,YAAY,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,YAAY,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC"}

package/declarations/store/-private/cache-handler/handler.d.ts

@@ -0,0 +1,57 @@
+import type { CacheHandler as CacheHandlerType } from '../../../request.ts';
+import type { ImmutableRequestInfo, RequestContext } from '../../../types/request.ts';
+import type { ResourceIdentifierObject } from '../../../types/spec/json-api-raw.ts';
+import type { RequestSignature } from '../../../types/symbols.ts';
+import type { Store } from '../store-service.ts';
+export type LooseStoreRequestInfo<RT = unknown, T = unknown> = Omit<ImmutableRequestInfo<RT, T>, 'records' | 'headers' | typeof RequestSignature> & {
+    records?: ResourceIdentifierObject[];
+    headers?: Headers;
+};
+export type StoreRequestInput<RT = unknown, T = unknown> = ImmutableRequestInfo<RT, T> | LooseStoreRequestInfo<RT, T>;
+export interface StoreRequestContext extends RequestContext {
+    request: ImmutableRequestInfo & {
+        store: Store;
+    };
+}
+/**
+ * A CacheHandler that adds support for using an WarpDrive Cache with a RequestManager.
+ *
+ * This handler will only run when a request has supplied a `store` instance. Requests
+ * issued by the store via `store.request()` will automatically have the `store` instance
+ * attached to the request.
+ *
+ * ```ts
+ * requestManager.request({
+ *   store: store,
+ *   url: '/api/posts',
+ *   method: 'GET'
+ * });
+ * ```
+ *
+ * When this handler elects to handle a request, it will return the raw `StructuredDocument`
+ * unless the request has `[EnableHydration]` set to `true`. In this case, the handler will
+ * return a `Document` instance that will automatically update the UI when the cache is updated
+ * in the future and will hydrate any identifiers in the StructuredDocument into Record instances.
+ *
+ * When issuing a request via the store, [EnableHydration] is automatically set to `true`. This
+ * means that if desired you can issue requests that utilize the cache without needing to also
+ * utilize Record instances if desired.
+ *
+ * Said differently, you could elect to issue all requests via a RequestManager, without ever using
+ * the store directly, by setting [EnableHydration] to `true` and providing a store instance. Not
+ * necessarily the most useful thing, but the decoupled nature of the RequestManager and incremental-feature
+ * approach of WarpDrive allows for this flexibility.
+ *
+ * ```ts
+ * import { EnableHydration } from '@warp-drive/core/types/request';
+ *
+ * requestManager.request({
+ *   store: store,
+ *   url: '/api/posts',
+ *   method: 'GET',
+ *   [EnableHydration]: true
+ * });
+ *
+ */
+export declare const CacheHandler: CacheHandlerType;
+//# sourceMappingURL=handler.d.ts.map

package/declarations/store/-private/cache-handler/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/store/-private/cache-handler/handler.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,IAAI,gBAAgB,EAA0C,MAAM,qBAAqB,CAAC;AAEpH,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EAGf,MAAM,2BAA2B,CAAC;AAInC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AACpF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAUjD,MAAM,MAAM,qBAAqB,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,IAAI,IAAI,CACjE,oBAAoB,CAAC,EAAE,EAAE,CAAC,CAAC,EAC3B,SAAS,GAAG,SAAS,GAAG,OAAO,gBAAgB,CAChD,GAAG;IACF,OAAO,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACrC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,IAAI,oBAAoB,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,qBAAqB,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAEtH,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD,OAAO,EAAE,oBAAoB,GAAG;QAAE,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC;CAClD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,YAAY,EAAE,gBA0E1B,CAAC"}

package/declarations/store/-private/cache-handler/types.d.ts

@@ -0,0 +1,99 @@
+import type { StableDocumentIdentifier } from '../../../types/identifier.ts';
+import type { ImmutableRequestInfo, ResponseInfo } from '../../../types/request.ts';
+import type { Store } from '../store-service';
+/**
+ * A service which an application may provide to the store via
+ * the store's `lifetimes` property to configure the behavior
+ * of the CacheHandler.
+ *
+ * The default behavior for request lifetimes is to never expire
+ * unless manually refreshed via `cacheOptions.reload` or `cacheOptions.backgroundReload`.
+ *
+ * Implementing this service allows you to programatically define
+ * when a request should be considered expired.
+ *
+ * @class (Interface) CachePolicy
+ * @public
+ */
+export interface CachePolicy {
+    /**
+     * Invoked to determine if the request may be fulfilled from cache
+     * if possible.
+     *
+     * Note, this is only invoked if the request has a cache-key.
+     *
+     * If no cache entry is found or the entry is hard expired,
+     * the request will be fulfilled from the configured request handlers
+     * and the cache will be updated before returning the response.
+     *
+     * @public
+     * @param {StableDocumentIdentifier} identifier
+     * @param {Store} store
+     * @return {Boolean} true if the request is considered hard expired
+     */
+    isHardExpired(identifier: StableDocumentIdentifier, store: Store): boolean;
+    /**
+     * Invoked if `isHardExpired` is false to determine if the request
+     * should be update behind the scenes if cache data is already available.
+     *
+     * Note, this is only invoked if the request has a cache-key.
+     *
+     * If true, the request will be fulfilled from cache while a backgrounded
+     * request is made to update the cache via the configured request handlers.
+     *
+     * @public
+     * @param {StableDocumentIdentifier} identifier
+     * @param {Store} store
+     * @return {Boolean} true if the request is considered soft expired
+     */
+    isSoftExpired(identifier: StableDocumentIdentifier, store: Store): boolean;
+    /**
+     * Invoked when a request will be sent to the configured request handlers.
+     * This is invoked for both foreground and background requests.
+     *
+     * Note, this is invoked regardless of whether the request has a cache-key.
+     *
+     * @public
+     * @param {ImmutableRequestInfo} request
+     * @param {StableDocumentIdentifier | null} identifier
+     * @param {Store} store
+     * @return {void}
+     */
+    willRequest?(request: ImmutableRequestInfo, identifier: StableDocumentIdentifier | null, store: Store): void;
+    /**
+     * Invoked when a request has been fulfilled from the configured request handlers.
+     * This is invoked for both foreground and background requests once the cache has
+     * been updated.
+     *
+     * Note, this is invoked regardless of whether the request has a cache-key.
+     *
+     * It is best practice to notify the store of any requests marked as invalidated
+     * so that request subscriptions can reload when needed.
+     *
+     * ```ts
+     * store.notifications.notify(identifier, 'invalidated');
+     * ```
+     *
+     * This allows anything subscribed to the request to be notified of the change
+     *
+     * e.g.
+     *
+     * ```ts
+     * store.notifications.subscribe(identifier, (_, type) => {
+     *   if (type === 'invalidated') {
+     *     // do update
+     *   }
+     * });
+     * ```
+     *
+     *
+     * @public
+     * @param {ImmutableRequestInfo} request
+     * @param {ImmutableResponse} response
+     * @param {StableDocumentIdentifier | null} identifier
+     * @param {Store} store
+     * @return {void}
+     */
+    didRequest?(request: ImmutableRequestInfo, response: Response | ResponseInfo | null, identifier: StableDocumentIdentifier | null, store: Store): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/declarations/store/-private/cache-handler/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/store/-private/cache-handler/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,UAAU,EAAE,wBAAwB,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IAC3E;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,UAAU,EAAE,wBAAwB,EAAE,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IAE3E;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,wBAAwB,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAE7G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,UAAU,CAAC,CACT,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,QAAQ,GAAG,YAAY,GAAG,IAAI,EACxC,UAAU,EAAE,wBAAwB,GAAG,IAAI,EAC3C,KAAK,EAAE,KAAK,GACX,IAAI,CAAC;CACT"}

package/declarations/store/-private/cache-handler/utils.d.ts

@@ -0,0 +1,32 @@
+import type { StableDocumentIdentifier } from '../../../types/identifier.ts';
+import type { ImmutableCreateRequestOptions, ImmutableDeleteRequestOptions, ImmutableRequestInfo, ImmutableUpdateRequestOptions, StructuredDataDocument } from '../../../types/request.ts';
+import type { ResourceDataDocument, ResourceErrorDocument } from '../../../types/spec/document.ts';
+import type { ApiError } from '../../../types/spec/error.ts';
+import type { Store } from '../store-service.ts';
+export declare const MUTATION_OPS: Set<string>;
+export declare function calcShouldFetch(store: Store, request: ImmutableRequestInfo, hasCachedValue: boolean, identifier: StableDocumentIdentifier | null): boolean;
+export declare function calcShouldBackgroundFetch(store: Store, request: ImmutableRequestInfo, willFetch: boolean, identifier: StableDocumentIdentifier | null): boolean;
+export declare function isMutation(request: Partial<ImmutableRequestInfo>): request is ImmutableUpdateRequestOptions | ImmutableCreateRequestOptions | ImmutableDeleteRequestOptions;
+export declare function isCacheAffecting<T>(document: StructuredDataDocument<T>): boolean;
+export declare function isAggregateError(error: Error & {
+    errors?: ApiError[];
+}): error is AggregateError & {
+    errors: ApiError[];
+};
+export type RobustError = Error & {
+    error: string | object;
+    errors?: ApiError[];
+    content?: unknown;
+};
+export declare function cloneError(error: RobustError): RobustError;
+export declare function isErrorDocument(document: ResourceDataDocument | ResourceErrorDocument): document is ResourceErrorDocument;
+export declare function getPriority(identifier: StableDocumentIdentifier | null, deduped: Map<StableDocumentIdentifier, {
+    priority: {
+        blocking: boolean;
+    };
+}>, priority: {
+    blocking: boolean;
+}): {
+    blocking: boolean;
+};
+//# sourceMappingURL=utils.d.ts.map

package/declarations/store/-private/cache-handler/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../../src/store/-private/cache-handler/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EACV,6BAA6B,EAC7B,6BAA6B,EAC7B,oBAAoB,EACpB,6BAA6B,EAC7B,sBAAsB,EACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACnG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,eAAO,MAAM,YAAY,aAA4D,CAAC;AAEtF,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,oBAAoB,EAC7B,cAAc,EAAE,OAAO,EACvB,UAAU,EAAE,wBAAwB,GAAG,IAAI,GAC1C,OAAO,CAQT;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,oBAAoB,EAC7B,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,wBAAwB,GAAG,IAAI,GAC1C,OAAO,CAOT;AAED,wBAAgB,UAAU,CACxB,OAAO,EAAE,OAAO,CAAC,oBAAoB,CAAC,GACrC,OAAO,IAAI,6BAA6B,GAAG,6BAA6B,GAAG,6BAA6B,CAE1G;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,OAAO,CAahF;AAED,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,GAAG;IAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAA;CAAE,GACrC,KAAK,IAAI,cAAc,GAAG;IAAE,MAAM,EAAE,QAAQ,EAAE,CAAA;CAAE,CAElD;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG;IAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAGrG,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,eAa5C;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,oBAAoB,GAAG,qBAAqB,GACrD,QAAQ,IAAI,qBAAqB,CAEnC;AAED,wBAAgB,WAAW,CACzB,UAAU,EAAE,wBAAwB,GAAG,IAAI,EAC3C,OAAO,EAAE,GAAG,CAAC,wBAAwB,EAAE;IAAE,QAAQ,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAAC,EAC3E,QAAQ,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE;cADgC,OAAO;EAUvE"}

package/declarations/store/-private/caches/cache-utils.d.ts

@@ -0,0 +1,9 @@
+import type { Cache } from '../../../types/cache.ts';
+import type { StableRecordIdentifier } from '../../../types/identifier.ts';
+import type { OpaqueRecordInstance } from '../../-types/q/record-instance';
+export declare const CacheForIdentifierCache: Map<unknown, Cache>;
+export declare function setCacheFor(identifier: StableRecordIdentifier | OpaqueRecordInstance, cache: Cache): void;
+export declare function removeRecordDataFor(identifier: StableRecordIdentifier | OpaqueRecordInstance): void;
+export declare function peekCache(instance: StableRecordIdentifier): Cache | null;
+export declare function peekCache(instance: OpaqueRecordInstance): Cache;
+//# sourceMappingURL=cache-utils.d.ts.map

package/declarations/store/-private/caches/cache-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-utils.d.ts","sourceRoot":"","sources":["../../../../src/store/-private/caches/cache-utils.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAO3E,eAAO,MAAM,uBAAuB,qBAGnC,CAAC;AAEF,wBAAgB,WAAW,CAAC,UAAU,EAAE,sBAAsB,GAAG,oBAAoB,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAMzG;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,sBAAsB,GAAG,oBAAoB,GAAG,IAAI,CAEnG;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,sBAAsB,GAAG,KAAK,GAAG,IAAI,CAAC;AAC1E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,KAAK,CAAC"}