@warp-drive/experiments 0.2.4-beta.0 → 0.2.4-beta.1

package/addon-main.cjs

@@ -1,5 +1,5 @@
 'use strict';
 
-const { addonShim } = require('@warp-drive/build-config/addon-shim.cjs');
+const { addonShim } = require('@warp-drive/core/addon-shim.cjs');
 
 module.exports = addonShim(__dirname);

package/declarations/data-worker/cache-handler.d.ts

@@ -0,0 +1,7 @@
+import type { CacheHandler as CacheHandlerType } from "@warp-drive/core/request";
+/**
+* A simplified CacheHandler that hydrates ResourceDataDocuments from the cache
+* with their referenced resources.
+*
+*/
+export declare const CacheHandler: CacheHandlerType;

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

@@ -0,0 +1,21 @@
+import type { Context, Deferred, Future, NextFn } from "@warp-drive/core/request";
+import type { AbortEventData, RequestEventData } from "./types.js";
+interface PendingItem {
+	context: Context;
+	signal: AbortSignal | null;
+	abortFn: () => void;
+	deferred: Deferred<unknown>;
+	stack: string;
+}
+export declare class WorkerFetch {
+	worker: Worker | SharedWorker;
+	threadId: string;
+	pending: Map<number, PendingItem>;
+	channel: MessageChannel;
+	constructor(worker: Worker | SharedWorker | null);
+	cleanupRequest(id: number): PendingItem | undefined;
+	send(event: RequestEventData | AbortEventData): void;
+	request<T>(context: Context, next: NextFn<T>): Promise<T> | Future<T>;
+}
+export declare function enhanceReason(reason?: string): DOMException;
+export {};

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

@@ -0,0 +1,31 @@
+import type { RequestInfo, StructuredDataDocument, StructuredErrorDocument } from "@warp-drive/core/types/request";
+export type SuccessResponseEventData<T> = {
+	type: "success-response";
+	thread: string;
+	id: number;
+	data: StructuredDataDocument<T>;
+};
+export type ErrorResponseEventData<T> = {
+	type: "error-response";
+	thread: string;
+	id: number;
+	data: StructuredErrorDocument<T>;
+};
+export type RequestEventData = {
+	type: "request";
+	thread: string;
+	id: number;
+	data: RequestInfo;
+};
+export type AbortEventData = {
+	type: "abort";
+	thread: string;
+	id: number;
+	data: string;
+};
+export type ThreadInitEventData = {
+	type: "connect";
+	thread: string;
+};
+export type MainThreadEvent<T> = MessageEvent<SuccessResponseEventData<T> | ErrorResponseEventData<T>>;
+export type WorkerThreadEvent = MessageEvent<RequestEventData> | MessageEvent<ThreadInitEventData> | MessageEvent<AbortEventData>;

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

@@ -0,0 +1,21 @@
+import type { Store } from "@warp-drive/core";
+import type { StableDocumentIdentifier } from "@warp-drive/core/types/identifier";
+import type { ImmutableCreateRequestOptions, ImmutableDeleteRequestOptions, ImmutableRequestInfo, ImmutableUpdateRequestOptions, StructuredDataDocument } from "@warp-drive/core/types/request";
+import type { ApiError } from "@warp-drive/core/types/spec/error";
+export declare const MUTATION_OPS: Set<string>;
+/**
+* In a Worker, any time we are asked to make a request, data needs to be returned.
+* background requests are ergo no different than foreground requests.
+* @internal
+*/
+export declare function calcShouldFetch(store: Store, request: ImmutableRequestInfo, hasCachedValue: 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;
+type RobustError = Error & {
+	error: string | object;
+	errors?: ApiError[];
+	content?: unknown;
+};
+// TODO @runspired, consider if we should deep freeze errors (potentially only in debug) vs cloning them
+export declare function cloneError(error: RobustError): RobustError;
+export {};

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

@@ -0,0 +1,23 @@
+import type { Store } from "@warp-drive/core";
+import type { Future } from "@warp-drive/core/request";
+import { DocumentStorage } from "../document-storage.js";
+import type { AbortEventData, RequestEventData } from "./types.js";
+export 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>;
+}

package/declarations/data-worker.d.ts

@@ -0,0 +1,2 @@
+export { DataWorker } from "./data-worker/worker.js";
+export { CacheHandler } from "./data-worker/cache-handler.js";

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

@@ -0,0 +1,90 @@
+import type { ExistingRecordIdentifier } from "@warp-drive/core/types/identifier";
+import type { StructuredDocument } from "@warp-drive/core/types/request";
+import type { ResourceDataDocument, ResourceDocument } from "@warp-drive/core/types/spec/document";
+import type { ExistingResourceObject } from "@warp-drive/core/types/spec/json-api-raw";
+export declare const WARP_DRIVE_STORAGE_FILE_NAME = "warp-drive_document-storage";
+export declare const WARP_DRIVE_STORAGE_VERSION = 1;
+export 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<ExistingRecordIdentifier>>;
+/**
+* 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: ExistingRecordIdentifier) => ExistingResourceObject): Promise<void>;
+	_getResources(document: ResourceDataDocument<ExistingRecordIdentifier>, resourceCollector: (resourceIdentifier: ExistingRecordIdentifier) => ExistingResourceObject, resources?: Map<string, ExistingResourceObject>): Map<string, ExistingResourceObject>;
+	putResources(document: ResourceDataDocument<ExistingRecordIdentifier>, resourceCollector: (resourceIdentifier: ExistingRecordIdentifier) => 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
+*/
+export declare class DocumentStorage {
+	readonly _storage: InternalDocumentStorage;
+	constructor(options?: Partial<DocumentStorageOptions>);
+	getDocument(key: DocumentIdentifier): Promise<CacheDocument | null>;
+	putDocument(document: CacheFileDocument, resourceCollector: (resourceIdentifier: ExistingRecordIdentifier) => ExistingResourceObject): Promise<void>;
+	putResources(document: ResourceDataDocument<ExistingRecordIdentifier>, resourceCollector: (resourceIdentifier: ExistingRecordIdentifier) => ExistingResourceObject): Promise<void>;
+	clear(reset?: boolean): Promise<void>;
+}
+export {};

package/declarations/document-storage.d.ts

@@ -0,0 +1 @@
+export { DocumentStorage } from "./document-storage/index.js";

package/declarations/image-fetch.d.ts

@@ -0,0 +1 @@
+export { ImageFetch } from "./image-worker/fetch.js";

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

@@ -0,0 +1,18 @@
+import type { Deferred } from "@warp-drive/core/request";
+import type { RequestEventData } from "./types.js";
+export interface FastBoot {
+	require(moduleName: string): unknown;
+	isFastBoot: boolean;
+	request: Request;
+}
+export declare class ImageFetch {
+	worker: Worker | SharedWorker;
+	threadId: string;
+	pending: Map<string, Deferred<string>>;
+	channel: MessageChannel;
+	cache: Map<string, string>;
+	constructor(worker: Worker | SharedWorker | null);
+	cleanupRequest(url: string): Deferred<string> | undefined;
+	_send(event: RequestEventData): void;
+	load(url: string): Promise<string>;
+}

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

@@ -0,0 +1,21 @@
+export type SuccessResponseEventData = {
+	type: "success-response";
+	thread: string;
+	url: string;
+};
+export type ErrorResponseEventData = {
+	type: "error-response";
+	thread: string;
+	url: string;
+};
+export type RequestEventData = {
+	type: "load";
+	thread: string;
+	url: string;
+};
+export type ThreadInitEventData = {
+	type: "connect";
+	thread: string;
+};
+export type MainThreadEvent = MessageEvent<SuccessResponseEventData | ErrorResponseEventData>;
+export type WorkerThreadEvent = MessageEvent<RequestEventData> | MessageEvent<ThreadInitEventData>;

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

@@ -0,0 +1,14 @@
+export declare class ImageWorker {
+	private threads;
+	private pendingImages;
+	private options;
+	private isSharedWorker;
+	private cache;
+	constructor(options?: {
+		persisted: boolean;
+	});
+	private fetch;
+	private initialize;
+	private setupThread;
+	private request;
+}

package/declarations/image-worker.d.ts

@@ -0,0 +1 @@
+export { ImageWorker } from "./image-worker/worker.js";