fetchium 0.0.0 → 0.1.0

package/dist/esm/QueryClient.d.ts

@@ -0,0 +1,76 @@
+import { ReactiveTask, type Context } from 'signalium';
+import { EntityDef, MutationEvent, QueryPromise, InternalTypeDef } from './types.js';
+import { EntityStore } from './EntityStore.js';
+import { EntityInstance } from './EntityInstance.js';
+import { NetworkManager } from './NetworkManager.js';
+import { QueryInstance } from './QueryResult.js';
+import { MutationResultImpl } from './MutationResult.js';
+import { MutationDefinition } from './mutation.js';
+import { GcManager, NoOpGcManager } from './GcManager.js';
+import { Query, QueryDefinition } from './query.js';
+import { type ParseResult } from './parseEntities.js';
+import { type ApplyResult } from './applyEntities.js';
+import { ValidatorDef } from './typeDefs.js';
+import { ConstraintMatcher } from './ConstraintMatcher.js';
+import { LiveCollectionBinding } from './LiveCollection.js';
+import { type QueryContext, type QueryStore, type QueryParams, type PreloadedEntityMap } from './query-types.js';
+export { type QueryContext, type QueryCacheOptions, type QueryConfigOptions, type LoadNextConfig, type QueryParams, type QueryStore, type CachedQuery, type PreloadedEntityMap, type MaybePromise, resolveBaseUrl, extractParamsForKey, queryKeyFor, } from './query-types.js';
+export declare class QueryClient {
+    private context;
+    entityMap: EntityStore;
+    queryInstances: Map<number, QueryInstance<any>>;
+    mutationInstances: Map<string, MutationResultImpl<unknown, unknown>>;
+    gcManager: GcManager | NoOpGcManager;
+    networkManager: NetworkManager;
+    isServer: boolean;
+    store: QueryStore;
+    currentParseId: number;
+    private typenameRegistry;
+    private constraintRegistry;
+    private mergedDefCache;
+    constructor(store: QueryStore, context?: QueryContext, networkManager?: NetworkManager, gcManager?: GcManager | NoOpGcManager);
+    getContext(): QueryContext;
+    private registerEntityDef;
+    getEntityDefsForTypename(typename: string): ValidatorDef<any>[] | undefined;
+    getMergedDef(typename: string): ValidatorDef<any> | undefined;
+    saveQueryData(queryDef: QueryDefinition<QueryParams | undefined, unknown, unknown>, queryKey: number, data: unknown, updatedAt: number, entityRefs?: Map<EntityInstance, number>): void;
+    activateQuery(queryInstance: QueryInstance<any>): void;
+    loadCachedQuery(queryDef: QueryDefinition<QueryParams | undefined, unknown, unknown>, queryKey: number): import("./query-types.js").MaybePromise<import("./query-types.js").CachedQuery | undefined>;
+    /**
+     * Loads a query from the document store and returns a QueryResult
+     * that triggers fetches and prepopulates with cached data
+     */
+    getQuery<T extends Query>(queryDef: QueryDefinition<any, any, any>, params: QueryParams | undefined): QueryPromise<T>;
+    /**
+     * Gets or creates a MutationResult for the given mutation definition.
+     * Mutations are cached by their definition ID.
+     */
+    getMutation<Request, Response>(mutationDef: MutationDefinition<Request, Response>): ReactiveTask<Response, [Request]>;
+    /**
+     * Parse data: validates, formats, produces parsed entity data objects.
+     * Does NOT touch the entity store. Call applyRefs() after to commit entities.
+     */
+    parseData(obj: unknown, shape: InternalTypeDef, preloadedEntities?: PreloadedEntityMap): ParseResult;
+    /**
+     * Apply entities from parseData() via a single depth-first walk: creates/
+     * updates EntityInstances, replaces parsed data with proxies, counts child
+     * refs. Returns the reified data and root-level entity refs.
+     */
+    applyRefs(parseResult: ParseResult, persist?: boolean, appendMode?: boolean): ApplyResult;
+    /**
+     * Parse and apply data as a root entity. For non-entity results, injects
+     * QUERY_ID onto the payload. Returns the root EntityInstance (created or
+     * found in the store by the standard entity pipeline).
+     */
+    parseAndApplyRootEntity(obj: unknown, queryId: number, rootEntityShape: ValidatorDef<any>, persist: boolean, appendMode?: boolean, preloadedEntities?: PreloadedEntityMap): EntityInstance;
+    prepareEntity(key: number, obj: Record<string, unknown>, shape: EntityDef): EntityInstance;
+    applyMutationEvent(event: MutationEvent): void;
+    private handleEviction;
+    getOrCreateMatcher(typename: string): ConstraintMatcher;
+    registerLiveCollection(binding: LiveCollectionBinding): void;
+    unregisterLiveCollection(binding: LiveCollectionBinding): void;
+    private routeEvent;
+    destroy(): void;
+}
+export declare const QueryClientContext: Context<QueryClient | undefined>;
+//# sourceMappingURL=QueryClient.d.ts.map

package/dist/esm/QueryClient.d.ts.map

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

package/dist/esm/QueryResult.d.ts

@@ -0,0 +1,67 @@
+import { DiscriminatedReactivePromise } from 'signalium';
+import { type QueryResult } from './types.js';
+import { type QueryClient, type QueryParams, type QueryConfigOptions } from './QueryClient.js';
+import { Query, QueryDefinition, type ResolvedRetryConfig } from './query.js';
+import { EntityInstance } from './EntityInstance.js';
+/**
+ * Thin fetch/relay orchestrator. Data management (proxy, notifier, child refs,
+ * live collections) is fully delegated to a root EntityInstance.
+ */
+export declare class QueryInstance<T extends Query> {
+    def: QueryDefinition<any, any, any>;
+    queryKey: number;
+    storageKey: number;
+    /** The public-facing ReactivePromise returned to consumers. */
+    readonly relay: DiscriminatedReactivePromise<QueryResult<T>>;
+    private queryClient;
+    private initialized;
+    private updatedAt;
+    private params;
+    private unsubscribe?;
+    private _relayState;
+    private wasPaused;
+    private currentParams;
+    private debounceTimer;
+    /** Resolved per-instance options (depend on actual params). */
+    config: QueryConfigOptions | undefined;
+    retryConfig: ResolvedRetryConfig;
+    /** The raw fetch Response from the most recent successful fetch. */
+    private _lastResponse;
+    /** Controller for aborting in-flight fetches and retry waits. */
+    private _abortController;
+    /** Cached execution context, recreated only when storageKey (params) changes. */
+    private _executionCtx;
+    private _executionCtxKey;
+    /** Root entity that holds parsed data, proxy, child refs, and bindings.
+     *  For entity results, this is undefined until the first apply discovers it. */
+    rootEntity: EntityInstance | undefined;
+    /** Extra methods (__refetch, __loadNext) attached to the root entity proxy. */
+    private _extraMethods;
+    /** Query id injected as QUERY_ID on non-entity payloads. */
+    private _queryId;
+    get key(): number;
+    private get relayState();
+    constructor(def: QueryDefinition<any, any, any>, queryClient: QueryClient, queryKey: number, params: QueryParams | undefined);
+    /** Apply raw data (fresh or cached) to the root entity and return the proxy. */
+    private applyData;
+    /** Save query metadata (the __entityRef pointer, updatedAt, ref set). */
+    private saveQueryMetadata;
+    private initialize;
+    private setupSubscription;
+    private getOrCreateExecutionContext;
+    private resolveAndApplyOptions;
+    private runQuery;
+    private runQueryImmediately;
+    private runDebounced;
+    refetch: () => DiscriminatedReactivePromise<QueryResult<T>>;
+    /** In-flight loadNext promise for deduplication. */
+    private _loadNextPromise;
+    /** Controller for aborting in-flight loadNext requests. */
+    private _loadNextAbort;
+    loadNext: () => Promise<QueryResult<T>>;
+    private get hasNext();
+    private runLoadNext;
+    private get isStale();
+    private get isPaused();
+}
+//# sourceMappingURL=QueryResult.d.ts.map

package/dist/esm/QueryResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryResult.d.ts","sourceRoot":"","sources":["../../src/QueryResult.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,4BAA4B,EAAE,MAAM,WAAW,CAAC;AACjF,OAAO,EAAe,KAAK,WAAW,EAAkB,MAAM,YAAY,CAAC;AAC3E,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EAIxB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAsB,MAAM,YAAY,CAAC;AAClG,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD;;;GAGG;AACH,qBAAa,aAAa,CAAC,CAAC,SAAS,KAAK;IACxC,GAAG,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAM;IAExB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,4BAA4B,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7D,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,MAAM,CAAsC;IAEpD,OAAO,CAAC,WAAW,CAAC,CAAyB;IAE7C,OAAO,CAAC,WAAW,CAAqD;IACxE,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,aAAa,CAAwD;IAE7E,+DAA+D;IAC/D,MAAM,EAAE,kBAAkB,GAAG,SAAS,CAAa;IACnD,WAAW,EAAE,mBAAmB,CAAiC;IAEjE,oEAAoE;IACpE,OAAO,CAAC,aAAa,CAAmC;IAExD,iEAAiE;IACjE,OAAO,CAAC,gBAAgB,CAA0C;IAElE,iFAAiF;IACjF,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,gBAAgB,CAAc;IAEtC;oFACgF;IAChF,UAAU,EAAE,cAAc,GAAG,SAAS,CAAC;IAEvC,+EAA+E;IAC/E,OAAO,CAAC,aAAa,CAAuD;IAE5E,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAa;IAE7B,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,OAAO,KAAK,UAAU,GAKrB;gBAGC,GAAG,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,EACnC,WAAW,EAAE,WAAW,EACxB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,WAAW,GAAG,SAAS;IA2FjC,gFAAgF;IAChF,OAAO,CAAC,SAAS;IA4BjB,yEAAyE;IACzE,OAAO,CAAC,iBAAiB;YAaX,UAAU;IAuCxB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,2BAA2B;IAiBnC,OAAO,CAAC,sBAAsB;YAMhB,QAAQ;IAqCtB,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,YAAY;IAiBpB,OAAO,QAAO,4BAA4B,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAIxD;IAEF,oDAAoD;IACpD,OAAO,CAAC,gBAAgB,CAAkD;IAE1E,2DAA2D;IAC3D,OAAO,CAAC,cAAc,CAA0C;IAEhE,QAAQ,QAAO,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CA4BpC;IAEF,OAAO,KAAK,OAAO,GAMlB;YAEa,WAAW;IAiCzB,OAAO,KAAK,OAAO,GAOlB;IAED,OAAO,KAAK,QAAQ,GAiBnB;CACF"}

package/dist/esm/applyEntities.d.ts

@@ -0,0 +1,12 @@
+import type { EntityInstance } from './EntityInstance.js';
+import type { ParseContext } from './parseEntities.js';
+export interface ApplyResult {
+    data: unknown;
+    entityRefs: Map<EntityInstance, number>;
+}
+/**
+ * Single depth-first walk from the root that applies entities to the store,
+ * replaces parsed data objects with entity proxies, and counts child refs.
+ */
+export declare function applyEntityRefs(ctx: ParseContext, rootData: unknown, persist: boolean, appendMode?: boolean): ApplyResult;
+//# sourceMappingURL=applyEntities.d.ts.map

package/dist/esm/applyEntities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyEntities.d.ts","sourceRoot":"","sources":["../../src/applyEntities.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,oBAAoB,CAAC;AAYrE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,GAAG,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,OAAO,EACjB,OAAO,EAAE,OAAO,EAChB,UAAU,GAAE,OAAe,GAC1B,WAAW,CASb"}