@warp-drive-mirror/experiments 0.2.7-alpha.9 → 0.2.7-beta.1

package/CHANGELOG.md

@@ -1 +1,71 @@
 # @warp-drive-mirror/experiments Changelog
+
+## v5.6.0 (2025-07-01)
+
+#### :memo: Documentation
+
+* [#9991](https://github.com/warp-drive-data/warp-drive/pull/9991) chore: improve output of typedoc ([@runspired](https://github.com/runspired))
+* [#9989](https://github.com/warp-drive-data/warp-drive/pull/9989) [BREAKING] docs: integrate API docs to the new docs site ([@runspired](https://github.com/runspired))
+
+#### :rocket: Enhancement
+
+* [#9998](https://github.com/warp-drive-data/warp-drive/pull/9998) feat: extract @ember-data-mirror/store => @warp-drive-mirror/core ([@runspired](https://github.com/runspired))
+
+#### :house: Internal
+
+* [#9994](https://github.com/warp-drive-data/warp-drive/pull/9994) chore: [@warp-drive-mirror/core] migrate @warp-drive-mirror/core-types @ember-data-mirror/request ([@runspired](https://github.com/runspired))
+
+#### Committers: (1)
+
+Chris Thoburn ([@runspired](https://github.com/runspired))
+
+## v5.5.0 (2025-05-08)
+
+#### :memo: Documentation
+
+* [#9975](https://github.com/warp-drive-data/warp-drive/pull/9975) types: fixup PolarisMode schema types to check better ([@runspired](https://github.com/runspired))
+
+#### :rocket: Enhancement
+
+* [#9965](https://github.com/warp-drive-data/warp-drive/pull/9965) feat: universal reactivity hooks ([@runspired](https://github.com/runspired))
+
+#### :house: Internal
+
+* [#9965](https://github.com/warp-drive-data/warp-drive/pull/9965) feat: universal reactivity hooks ([@runspired](https://github.com/runspired))
+
+#### Committers: (1)
+
+Chris Thoburn ([@runspired](https://github.com/runspired))
+
+## v5.4.0 (2025-04-11)
+
+#### :memo: Documentation
+
+* [#9778](https://github.com/warp-drive-data/warp-drive/pull/9778) chore: improve contributing guidance for api documentation ([@runspired](https://github.com/runspired))
+* [#9648](https://github.com/warp-drive-data/warp-drive/pull/9648) docs: cleanup usage pattern for RequestManager configuration on store ([@runspired](https://github.com/runspired))
+* [#9512](https://github.com/warp-drive-data/warp-drive/pull/9512) Fix typos in README.md ([@johanrd](https://github.com/johanrd))
+
+#### :rocket: Enhancement
+
+* [#9884](https://github.com/warp-drive-data/warp-drive/pull/9884) feat: cache patch operations for relationships and documents ([@runspired](https://github.com/runspired))
+* [#9541](https://github.com/warp-drive-data/warp-drive/pull/9541) feat: eslint-plugin-(ember-data|warp-drive) ([@runspired](https://github.com/runspired))
+* [#9524](https://github.com/warp-drive-data/warp-drive/pull/9524) feat: persisted DataWorker and ImageWorker ([@runspired](https://github.com/runspired))
+* [#8698](https://github.com/warp-drive-data/warp-drive/pull/8698) feat: DataWorker | robust cross-tab request deduplication and replay ([@runspired](https://github.com/runspired))
+
+#### :house: Internal
+
+* [#9780](https://github.com/warp-drive-data/warp-drive/pull/9780) chore: bump @glimmer/component ([@runspired](https://github.com/runspired))
+* [#9759](https://github.com/warp-drive-data/warp-drive/pull/9759) chore: Improve contributing experience ([@runspired](https://github.com/runspired))
+* [#9752](https://github.com/warp-drive-data/warp-drive/pull/9752) chore: tooling upgrades to support WarpDrive package unification ([@runspired](https://github.com/runspired))
+* [#9705](https://github.com/warp-drive-data/warp-drive/pull/9705) chore: make diagnostic shutdown safer, use bun for holodeck server ([@runspired](https://github.com/runspired))
+* [#9697](https://github.com/warp-drive-data/warp-drive/pull/9697) chore: [BREAKING to prior alpha/betas] prepare SchemaRecord for stable, lockdown exports ([@runspired](https://github.com/runspired))
+* [#9629](https://github.com/warp-drive-data/warp-drive/pull/9629) fix: restore * versions and setup publish to not overwrite them ([@runspired](https://github.com/runspired))
+* [#9620](https://github.com/warp-drive-data/warp-drive/pull/9620) Starwars ([@NullVoxPopuli](https://github.com/NullVoxPopuli))
+* [#9596](https://github.com/warp-drive-data/warp-drive/pull/9596) chore: Remove unused `--report-unused-disable-directives` flag ([@gitKrystan](https://github.com/gitKrystan))
+
+#### Committers: (4)
+
+Chris Thoburn ([@runspired](https://github.com/runspired))
+[@johanrd](https://github.com/johanrd)
+[@NullVoxPopuli](https://github.com/NullVoxPopuli)
+Krystan HuffMenne ([@gitKrystan](https://github.com/gitKrystan))

package/README.md

@@ -27,4 +27,5 @@
 
 - [DataWorker](./src/data-worker/README.md)
 - [DocumentStorage](./src/document-storage/README.md)
-- [ImageWorker](./src/image-worker/README.md)
+- [ImageWorker](./src/image-worker.md)
+- ReactiveStorage

package/declarations/data-worker.d.ts

@@ -1,2 +1,35 @@
-export { DataWorker } from "./data-worker/worker.js";
-export { CacheHandler } from "./data-worker/cache-handler.js";
+import { t as DocumentStorage } from "./document-storage-CwwTQ49-.js";
+import { n as RequestEventData, t as AbortEventData } from "./types-CRs-Qww6.js";
+import { CacheHandler as CacheHandler$1, Future } from "@warp-drive-mirror/core/request";
+import { Store } from "@warp-drive-mirror/core";
+//#region src/data-worker/worker.d.ts
+declare class DataWorker {
+  store: Store;
+  threads: Map<string, MessagePort>;
+  pending: Map<string, Map<number, Future<unknown>>>;
+  isSharedWorker: boolean;
+  options: {
+    persisted: boolean;
+    scope?: string;
+  };
+  storage: DocumentStorage;
+  constructor(UserStore: typeof Store, options?: {
+    persisted: boolean;
+    scope?: string;
+  });
+  initialize(): void;
+  setupThread(thread: string, port: MessagePort): void;
+  abortRequest(event: AbortEventData): void;
+  request(event: RequestEventData): Promise<void>;
+}
+//#endregion
+//#region src/data-worker/cache-handler.d.ts
+/**
+ * A simplified CacheHandler that hydrates ResourceDataDocuments from the cache
+ * with their referenced resources.
+ *
+ */
+declare const CacheHandler: CacheHandler$1;
+//#endregion
+export { CacheHandler, DataWorker };
+//# sourceMappingURL=data-worker.d.ts.map

package/declarations/data-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-worker.d.ts","names":[],"sources":["../src/data-worker/worker.ts","../src/data-worker/cache-handler.ts"],"mappings":";;;;;cASa;EACX,OAAe;EACf,SAAiB,YAAY;EAC7B,SAAiB,YAAY,YAAY;EACzC;EACA;IAAmB;IAAoB;;EACvC,SAAiB;EAEjB,YAAY,kBAAkB,OAAO;IAAY;IAAoB;;EAarE;EAkCA,YAAY,gBAAgB,MAAM;EAqBlC,aAAa,OAAO;EAUpB,QAAc,OAAO,mBAAmB;;;;;;;;;cCnE7B,cAAc"}

package/declarations/document-storage-CwwTQ49-.d.ts

@@ -0,0 +1,91 @@
+import { StructuredDocument } from "@warp-drive-mirror/core/types/request";
+import { PersistedResourceKey } from "@warp-drive-mirror/core/types/identifier";
+import { ResourceDataDocument, ResourceDocument } from "@warp-drive-mirror/core/types/spec/document";
+import { ExistingResourceObject } from "@warp-drive-mirror/core/types/spec/json-api-raw";
+//#region src/document-storage/index.d.ts
+type DocumentStorageOptions = {
+  /**
+   * The scope of the storage. This is used to enable multiple distinct
+   * storage areas within the same origin.
+   *
+   * One use case for this is to have a separate storage area for each
+   * user credential. So for instance, in applications that allow a single
+   * user to have multiple accounts, each account can have its own storage!
+   */
+  scope: string;
+  /**
+   * When set to true, if other instances of the storage are created with
+   * the same scope, they will not share the same in-memory cache and BroadcastChannel.
+   *
+   * This is mostly useful for testing purposes to replicate the behavior of
+   * multiple tabs or workers.
+   */
+  isolated: boolean;
+};
+/**
+ * DocumentStorage is specifically designed around WarpDrive Cache and Request concepts.
+ *
+ * CacheFileDocument is a StructuredDocument (request response) whose `content` is
+ * the ResourceDocument returned by inserting the request into a Store's Cache.
+ */
+type CacheFileDocument = StructuredDocument<ResourceDocument>;
+/**
+ * A CacheDocument is a reconstructed request response that rehydrates ResourceDocument
+ * with the associated resources based on their identifiers.
+ */
+type CacheDocument = StructuredDocument<ResourceDocument<ExistingResourceObject>>;
+type DocumentIdentifier = {
+  lid: string;
+};
+type MemCache = {
+  documents: Map<string, CacheFileDocument>;
+  resources: Map<string, ExistingResourceObject>;
+};
+declare class InternalDocumentStorage {
+  readonly options: DocumentStorageOptions;
+  _fileHandle: Promise<FileSystemFileHandle>;
+  _channel: BroadcastChannel;
+  _invalidated: boolean;
+  _lastModified: number;
+  _cache: MemCache | null;
+  _filePromise: Promise<MemCache> | null;
+  constructor(options: DocumentStorageOptions);
+  _onMessage(_event: MessageEvent): void;
+  _open(scope: string): Promise<FileSystemFileHandle>;
+  _read(): Promise<MemCache>;
+  _patch(documentKey: string, document: CacheFileDocument, updatedResources: Map<string, ExistingResourceObject>): Promise<void>;
+  getDocument(key: DocumentIdentifier): Promise<CacheDocument | null>;
+  putDocument(document: CacheFileDocument, resourceCollector: (resourceIdentifier: PersistedResourceKey) => ExistingResourceObject): Promise<void>;
+  _getResources(document: ResourceDataDocument, resourceCollector: (resourceIdentifier: PersistedResourceKey) => ExistingResourceObject, resources?: Map<string, ExistingResourceObject>): Map<string, ExistingResourceObject>;
+  putResources(document: ResourceDataDocument, resourceCollector: (resourceIdentifier: PersistedResourceKey) => ExistingResourceObject): Promise<void>;
+  clear(reset?: boolean): Promise<void>;
+}
+/**
+ * DocumentStorage is a wrapper around the StorageManager API that provides
+ * a simple interface for reading and updating documents and requests.
+ *
+ * Some goals for this experiment:
+ *
+ * - optimize for storing requests/documents
+ * - optimize for storing resources
+ * - optimize for looking up resources associated to a document
+ * - optimize for notifying cross-tab when data is updated
+ *
+ * optional features:
+ *
+ * - support for offline mode
+ * - ?? support for relationship based cache traversal
+ * - a way to index records by type + another field (e.g updatedAt/createAt/name)
+ *   such that simple queries can be done without having to scan all records
+ */
+declare class DocumentStorage {
+  readonly _storage: InternalDocumentStorage;
+  constructor(options?: Partial<DocumentStorageOptions>);
+  getDocument(key: DocumentIdentifier): Promise<CacheDocument | null>;
+  putDocument(document: CacheFileDocument, resourceCollector: (resourceIdentifier: PersistedResourceKey) => ExistingResourceObject): Promise<void>;
+  putResources(document: ResourceDataDocument, resourceCollector: (resourceIdentifier: PersistedResourceKey) => ExistingResourceObject): Promise<void>;
+  clear(reset?: boolean): Promise<void>;
+}
+//#endregion
+export { DocumentStorage as t };
+//# sourceMappingURL=document-storage-CwwTQ49-.d.ts.map

package/declarations/document-storage-CwwTQ49-.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-storage-CwwTQ49-.d.ts","names":[],"sources":["../src/document-storage/index.ts"],"mappings":";;;;;KAUY;;;;;;;;;EASV;;;;;;;;EAQA;;;;;;;;KAQG,oBAAoB,mBAAmB;;;;;KAKvC,gBAAgB,mBAAmB,iBAAiB;KAMpD;EAAuB;;KAEvB;EACH,WAAW,YAAY;EACvB,WAAW,YAAY;;cAGnB;WACa,SAAS;EAC1B,aAAqB,QAAQ;EAC7B,UAAkB;EAClB;EACA;EACA,QAAgB;EAChB,cAAsB,QAAQ;EAE9B,YAAY,SAAS;EAWrB,WAAW,QAAQ;EAInB,MAAY,gBAAgB,QAAQ;EAMpC,SAAe,QAAQ;EAmCvB,OACE,qBACA,UAAU,mBACV,kBAAkB,YAAY,0BAC7B;EAuBH,YAAkB,KAAK,qBAAqB,QAAQ;EAqDpD,YACE,UAAU,mBACV,oBAAoB,oBAAoB,yBAAyB,yBAChE;EAkBH,cACE,UAAU,sBACV,oBAAoB,oBAAoB,yBAAyB,wBACjE,YAAW,YAAY,0BACtB,YAAY;EAqBf,aACE,UAAU,sBACV,oBAAoB,oBAAoB,yBAAyB,yBAChE;EAwBH,MAAY,kBAAkB;;;;;;;;;;;;;;;;;;;;cAuInB;WACM,UAAU;EAE3B,YAAY,UAAS,QAAQ;EAoB7B,YAAY,KAAK,qBAAqB,QAAQ;EAI9C,YACE,UAAU,mBACV,oBAAoB,oBAAoB,yBAAyB,yBAChE;EAIH,aACE,UAAU,sBACV,oBAAoB,oBAAoB,yBAAyB,yBAChE;EAIH,MAAM,kBAAkB"}

package/declarations/document-storage.d.ts

@@ -1 +1,2 @@
-export { DocumentStorage } from "./document-storage/index.js";
+import { t as DocumentStorage } from "./document-storage-CwwTQ49-.js";
+export { DocumentStorage };

package/declarations/image-fetch.d.ts

@@ -1 +1,60 @@
-export { ImageFetch } from "./image-worker/fetch.js";
+import { Deferred } from "@warp-drive-mirror/core/request";
+//#region src/image-worker/types.d.ts
+/** Sent by {@link ImageFetch} to request that an image url be loaded. */
+type RequestEventData = {
+  type: "load";
+  thread: string;
+  url: string;
+};
+//#endregion
+//#region src/image-worker/fetch.d.ts
+/**
+ * Main-thread client for an {@link ImageWorker}. Sends image `load`
+ * requests to a `Worker` or `SharedWorker` running an `ImageWorker`.
+ *
+ * In FastBoot/SSR, or when constructed with a `null` worker, `ImageFetch`
+ * skips worker communication entirely: {@link ImageFetch.load} resolves
+ * immediately with the given url.
+ *
+ * A plain `Worker` is only accepted when running in a `TESTING` build;
+ * production usage requires a `SharedWorker`.
+ *
+ * @public
+ */
+declare class ImageFetch {
+  worker: Worker | SharedWorker;
+  threadId: string;
+  pending: Map<string, Deferred<string>>;
+  channel: MessageChannel;
+  cache: Map<string, string>;
+  /**
+   * @param worker - the `Worker` or `SharedWorker` running an
+   * {@link ImageWorker}, or `null` to disable worker communication (e.g.
+   * in FastBoot/SSR).
+   */
+  constructor(worker: Worker | SharedWorker | null);
+  cleanupRequest(url: string): Deferred<string> | undefined;
+  _send(event: RequestEventData): void;
+  /**
+   * Requests that the given image url be loaded by the connected
+   * {@link ImageWorker}, resolving with an object url for the fetched
+   * image's blob once the worker responds (or immediately with the
+   * original `url`, in SSR/FastBoot or when this instance was constructed
+   * with a `null` worker).
+   *
+   * The resolved object url is cached in-memory by source url on this
+   * instance, so subsequent calls for the same url resolve immediately
+   * without another round-trip to the worker.
+   *
+   * Calling `load` again for a url that is already in-flight (not yet
+   * cached) on this instance replaces the pending request rather than
+   * joining it — only the most recently issued call for a given url will
+   * resolve.
+   *
+   * @public
+   */
+  load(url: string): Promise<string>;
+}
+//#endregion
+export { ImageFetch };
+//# sourceMappingURL=image-fetch.d.ts.map

package/declarations/image-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-fetch.d.ts","names":[],"sources":["../src/image-worker/types.ts","../src/image-worker/fetch.ts"],"mappings":";;;KA8BY;EACV;EACA;EACA;;;;;;;;;;;;;;;;;cCFW;EACX,QAAgB,SAAS;EACzB;EACA,SAAiB,YAAY;EAC7B,SAAiB;EACjB,OAAe;;;;;;EAOf,YAAY,QAAQ,SAAS;EA0C7B,eAAe,cAAc;EAO7B,MAAM,OAAO;;;;;;;;;;;;;;;;;;;EAuBb,KAAK,cAAc"}

package/declarations/image-worker.d.ts

@@ -1 +1,40 @@
-export { ImageWorker } from "./image-worker/worker.js";
+//#region src/image-worker/worker.d.ts
+/**
+ * Runs inside a `Worker` or `SharedWorker` to fetch images on behalf of
+ * one or more {@link ImageFetch} instances running on the main thread(s)
+ * that connect to it.
+ *
+ * Each connecting thread registers itself by sending a `connect` message
+ * along with a {@link MessagePort}. When a thread sends a `load` request
+ * for a url, the worker fetches the image via `fetch`, converts the
+ * response into a `Blob`, and creates an object url for it via
+ * `URL.createObjectURL`. The fetch for a given url is deduped and cached
+ * in-memory for the lifetime of the worker, so repeat `load` requests for
+ * the same url — whether from the same or a different connected thread —
+ * do not trigger another network request.
+ *
+ * Only intended for use inside a Worker context: constructing an
+ * `ImageWorker` on the main thread is a no-op.
+ *
+ * @public
+ */
+declare class ImageWorker {
+  private threads;
+  private pendingImages;
+  private options;
+  private isSharedWorker;
+  private cache;
+  /**
+   * @param options.persisted - reserved for a future on-disk cache; currently unused.
+   */
+  constructor(options?: {
+    persisted: boolean;
+  });
+  private fetch;
+  private initialize;
+  private setupThread;
+  private request;
+}
+//#endregion
+export { ImageWorker };
+//# sourceMappingURL=image-worker.d.ts.map

package/declarations/image-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-worker.d.ts","names":[],"sources":["../src/image-worker/worker.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;cA+Ba;UACK;UACA;UACA;UACA;UACA;;;;EAKhB,YAAY;IAAY;;UAahB;UAsBA;UA4BA;UAiBM"}