@codecks/fetch 0.1.4 → 0.1.6

package/dist/immediate-cache-DiH8tpJM.js

@@ -0,0 +1,237 @@
+//#region src/_exploration/optimistic-manager.ts
+/**
+* Represents a single optimistic update layer
+* Contains field updates for one mutation
+* Internal implementation - wrapped by ImmediateCache to provide full OptimisticUpdater interface
+*/
+var OptimisticLayer = class {
+	data = new Map();
+	affectedFields = new Set();
+	setField(model, id, field, value) {
+		const fieldKey = getFieldKey(model, id, field);
+		this.data.set(fieldKey, value);
+		this.affectedFields.add(fieldKey);
+	}
+	hasChanges() {
+		return this.affectedFields.size > 0;
+	}
+	getAffectedFieldKeys() {
+		return this.affectedFields;
+	}
+	entries() {
+		return this.data.entries();
+	}
+};
+/**
+* Manages a stack of optimistic layers with O(1) lookups
+*
+* Design:
+* - Maintains a stack of layers (one per in-flight mutation)
+* - Rebuilds flattened view when layers added/removed for fast reads
+* - Later layers override earlier ones (parallel updates supported)
+* - Auto-cleanup via promise lifecycle
+*/
+var OptimisticManager = class {
+	layers = [];
+	flatView = new Map();
+	/**
+	* Add a new optimistic layer
+	* @returns Object with the layer and a dispose function that returns affected field keys
+	*/
+	addLayer() {
+		const layer = new OptimisticLayer();
+		this.layers.push(layer);
+		const dispose = () => this.removeLayer(layer);
+		return {
+			layer,
+			dispose
+		};
+	}
+	/**
+	* Get optimistic value for a field (O(1) via flat view)
+	* Returns undefined if no optimistic update exists for this field
+	*/
+	get(model, id, field) {
+		const fieldKey = getFieldKey(model, id, field);
+		const entry = this.flatView.get(fieldKey);
+		if (!entry) return void 0;
+		const meta = { state: "optimistic" };
+		return {
+			value: entry.value,
+			partKeys: [fieldKey],
+			meta
+		};
+	}
+	/**
+	* Remove a layer from the stack
+	* Returns affected field keys for notification
+	*/
+	removeLayer(layer) {
+		const layerIndex = this.layers.indexOf(layer);
+		if (layerIndex === -1) return;
+		this.layers.splice(layerIndex, 1);
+		this.rebuildFlatView();
+	}
+	/**
+	* Rebuild the flattened view from the layer stack
+	* Later layers override earlier ones for the same field
+	*/
+	rebuildFlatView() {
+		this.flatView.clear();
+		for (let i = 0; i < this.layers.length; i++) {
+			const layer = this.layers[i];
+			for (const [fieldKey, value] of layer.entries()) this.flatView.set(fieldKey, {
+				value,
+				layerIndex: i
+			});
+		}
+	}
+};
+
+//#endregion
+//#region src/_exploration/immediate-cache.ts
+const getFieldKey = (model, id, field) => `${model}:${id}:${field}`;
+/**
+* Wrapper that provides full OptimisticUpdater interface
+* Delegates writes to OptimisticLayer and reads to ImmediateCache
+*/
+var OptimisticUpdater = class {
+	constructor(layer, cache) {
+		this.layer = layer;
+		this.cache = cache;
+	}
+	setField(model, id, field, value) {
+		this.layer.setField(model, id, field, value);
+	}
+	getField(model, id, field) {
+		return this.cache.get(model, id, field);
+	}
+};
+var ImmediateCache = class {
+	cache = new Map();
+	partKeyToFields = new Map();
+	fieldSubscriptions = new Map();
+	optimisticManager = new OptimisticManager();
+	getInstanceKey(model, id) {
+		return `${model}:${id}`;
+	}
+	get(model, key, field) {
+		const optimistic = this.optimisticManager.get(model, key, field);
+		if (optimistic) return optimistic;
+		return this.cache.get(this.getInstanceKey(model, key))?.get(field);
+	}
+	subscribe(fieldKey, notifyFn) {
+		const exists = this.fieldSubscriptions.get(fieldKey);
+		if (exists) exists.add(notifyFn);
+		else this.fieldSubscriptions.set(fieldKey, new Set([notifyFn]));
+		return () => {
+			const subs = this.fieldSubscriptions.get(fieldKey);
+			if (!subs) return;
+			subs.delete(notifyFn);
+			if (subs.size === 0) this.fieldSubscriptions.delete(fieldKey);
+		};
+	}
+	set(model, key, partialInstance, meta) {
+		const instanceKey = this.getInstanceKey(model, key);
+		let entry = this.cache.get(instanceKey);
+		if (!entry) {
+			entry = new Map();
+			this.cache.set(instanceKey, entry);
+		}
+		const subs = [];
+		for (const field in partialInstance) {
+			const f = partialInstance[field];
+			const oldEntry = entry.get(field);
+			const oldValue = oldEntry?.value;
+			const newValue = f.value;
+			const fieldEntry = {
+				value: newValue,
+				partKeys: f.partKeys,
+				meta
+			};
+			const fieldKey = getFieldKey(model, key, field);
+			entry.set(field, fieldEntry);
+			for (const partKey of f.partKeys) {
+				const location = {
+					model,
+					id: key,
+					field,
+					fieldKey,
+					cache: fieldEntry,
+					type: f.type
+				};
+				const maybeFields = this.partKeyToFields.get(partKey);
+				if (!maybeFields) this.partKeyToFields.set(partKey, [location]);
+				else maybeFields.push(location);
+			}
+			if (oldValue !== newValue) {
+				const fieldSubs = this.fieldSubscriptions.get(fieldKey);
+				if (fieldSubs) subs.push(...fieldSubs);
+			}
+		}
+		return subs;
+	}
+	markDirty(partKeys) {
+		const subscribedFields = [];
+		for (const partKey of partKeys) {
+			const locations = this.partKeyToFields.get(partKey);
+			console.log(locations);
+			if (!locations) continue;
+			for (const location of locations) {
+				location.cache.meta = { state: "dirty" };
+				if (this.fieldSubscriptions.has(location.fieldKey)) if (location.type === "field") subscribedFields.push({
+					type: "field",
+					model: location.model,
+					id: location.id,
+					field: location.field
+				});
+				else subscribedFields.push({
+					type: "relation",
+					model: location.model,
+					id: location.id,
+					relKey: location.fieldKey,
+					contents: {
+						asField: false,
+						fields: []
+					}
+				});
+			}
+		}
+		return subscribedFields;
+	}
+	/**
+	* Create a new optimistic layer bound to a promise and apply updates
+	* The layer will be automatically removed when the promise settles
+	* @param promise - Promise to bind the layer lifecycle to
+	* @param updateFn - Function to apply optimistic updates to the layer
+	* @returns The updater object with both read and write capabilities
+	*/
+	createOptimisticLayer(promise, updateFn) {
+		const { layer, dispose } = this.optimisticManager.addLayer();
+		const updater = new OptimisticUpdater(layer, this);
+		updateFn(updater);
+		if (layer.hasChanges()) {
+			this.optimisticManager.rebuildFlatView();
+			const affectedFields = layer.getAffectedFieldKeys();
+			const notify = () => {
+				const subs = [];
+				for (const fieldKey of affectedFields) {
+					const fieldSubs = this.fieldSubscriptions.get(fieldKey);
+					if (fieldSubs) subs.push(...fieldSubs);
+				}
+				new Set(subs).forEach((fn) => fn());
+			};
+			notify();
+			promise.finally(() => {
+				dispose();
+				notify();
+			});
+		} else promise.finally(() => {
+			dispose();
+		});
+		return updater;
+	}
+};
+
+//#endregion
+export { ImmediateCache, getFieldKey };

package/dist/{index-DUBsesYl.d.ts → index-obQtSRRg.d.ts}

@@ -1,4 +1,4 @@
-import { ModelDesc, Nominal, RelationEntry, TypedField } from "./query-type-Dx5ZCv5N.js";
+import { ModelDesc, Nominal, RelationEntry, TypedField } from "./query-type-B0L3hwCo.js";
 
 //#region src/models/AccountOnboardingStep.d.ts
 type AccountOnboardingStepId = Nominal<string, "accountOnboardingStep">;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { InferModelQuery, InferRelQuery, Instance, ModelQuery, RelQuery } from "./query-type-Dx5ZCv5N.js";
-import { modelMap$1 as modelMap } from "./index-DUBsesYl.js";
-import { DataLoader, FetchOptions } from "./loader-utils-Du-CTKH-.js";
-import { _rootDesc$1 as _rootDesc } from "./_root-D1Faf8cg.js";
+import { InferModelQuery, InferRelQuery, Instance, ModelQuery, RelQuery } from "./query-type-B0L3hwCo.js";
+import { modelMap$1 as modelMap } from "./index-obQtSRRg.js";
+import { DataLoader, FetchOptions } from "./loader-utils-rQFSDhwf.js";
+import { _rootDesc$1 as _rootDesc } from "./_root-rBEjvjCJ.js";
 
 //#region src/loaders/simple-loader.d.ts
 type SimpleLoaderOptions = FetchOptions;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { configuredFetch, ensureMapValue } from "./collection-utils-CYJaA1a9.js";
-import { _rootDesc, getRelKey, makeModelQuerySerializable, modelMap, serializeInstanceQuery } from "./query-helpers-DsMMOtSO.js";
+import { _rootDesc, getRelKey, makeModelQuerySerializable, modelMap, serializeInstanceQuery } from "./query-helpers-DgC42MEH.js";
 
 //#region src/model-pool.ts
 const ROOT_ID = "";
@@ -12,7 +12,7 @@ const dateStrToDay = (dateAsStr) => {
 	};
 };
 const parseField = (v, field) => {
-	if (!field) return v;
+	if (!field || v == null) return v;
 	switch (field.type) {
 		case "date": return new Date(v);
 		case "day": return dateStrToDay(v);
@@ -75,10 +75,11 @@ const reconcileInstanceQuery = (query, response, instanceModel, key, store) => {
 			switch (opts.type) {
 				case "belongsTo":
 					result[opts.fk] = instance[relName];
-					result[relName] = opts.fk ? reconcileInstanceQuery(relEntry, response, relModel, `${instance[relName]}`, store) : null;
+					result[`~${relName}`] = instance[relName] != null ? `${instance[relName]}` : null;
+					result[relName] = instance[relName] != null ? reconcileInstanceQuery(relEntry, response, relModel, `${instance[relName]}`, store) : null;
 					break;
 				case "hasOne":
-					result[`~${relName}`] = instance[relName];
+					result[`~${relName}`] = instance[relName] != null ? `${instance[relName]}` : null;
 					result[relName] = reconcileInstanceQuery(relEntry, response, relModel, `${instance[relName]}`, store);
 					break;
 				case "hasMany":
@@ -92,11 +93,11 @@ const reconcileInstanceQuery = (query, response, instanceModel, key, store) => {
 							break;
 						}
 						case "first":
-							result[`~${asName}`] = val;
+							result[`~${asName}`] = val != null ? `${val}` : null;
 							result[asName] = reconcileInstanceQuery(relEntry, response, relModel, `${val}`, store);
 							break;
 						default: {
-							result[`~${asName}`] = val;
+							result[`~${asName}`] = val.map((v) => `${v}`);
 							result[asName] = val.map((id) => reconcileInstanceQuery(relEntry, response, relModel, `${id}`, store));
 						}
 					}

package/dist/{loader-types-Dp0CSVTf.d.ts → loader-types-Y0OHlOEK.d.ts}

@@ -1,4 +1,4 @@
-import { SerializableRelationQuery } from "./query-type-Dx5ZCv5N.js";
+import { SerializableRelationQuery } from "./query-type-B0L3hwCo.js";
 
 //#region src/_exploration/loader-types.d.ts
 type OnLoadedFn = (model: string, key: string, partialInstance: Record<string, unknown>) => void;
@@ -6,16 +6,12 @@ interface BaseLoader {
   setOnLoaded(onLoaded: OnLoadedFn): void;
   loadBatch(requests: MissingDataRequest[]): Promise<unknown>;
 }
-type LoaderPayload = {
-  value: unknown;
-  partKeys: string[];
-};
 type LoaderResult = {
   state: "resolved";
-  payload: LoaderPayload;
+  payload: unknown;
 } | {
   state: "pending";
-  promise: Promise<LoaderPayload>;
+  promise: Promise<unknown>;
 };
 type MissingDataRequest = {
   type: "field";
@@ -27,7 +23,7 @@ type MissingDataRequest = {
   model: string;
   id: string;
   relKey: string;
-  query: SerializableRelationQuery;
+  contents: SerializableRelationQuery;
 };
 interface BaseRequester {
   request: (requests: MissingDataRequest[]) => Promise<{

package/dist/{loader-utils-Du-CTKH-.d.ts → loader-utils-rQFSDhwf.d.ts}

@@ -1,5 +1,5 @@
-import { InferModelQuery, ModelQuery } from "./query-type-Dx5ZCv5N.js";
-import { modelMap$1 as modelMap } from "./index-DUBsesYl.js";
+import { InferModelQuery, ModelQuery } from "./query-type-B0L3hwCo.js";
+import { modelMap$1 as modelMap } from "./index-obQtSRRg.js";
 
 //#region src/loaders/loader-utils.d.ts
 type ModelMap = typeof modelMap;

package/dist/{query-helpers-DsMMOtSO.js → query-helpers-DgC42MEH.js}

@@ -33,33 +33,37 @@ const _rootDesc = makeModel({
 const id = () => {
 	return { type: "id" };
 };
+const withOpts = (type, opts) => opts.optional ? {
+	type,
+	optional: true
+} : { type };
 const string = (opts) => {
-	return { type: "string" };
+	return withOpts("string", opts);
 };
 const int = (opts) => {
-	return { type: "int" };
+	return withOpts("int", opts);
 };
 const bigint = (opts) => {
-	return { type: "bigint" };
+	return withOpts("bigint", opts);
 };
 const bool = (opts) => {
-	return { type: "bool" };
+	return withOpts("bool", opts);
 };
 const date = (opts) => {
-	return { type: "date" };
+	return withOpts("date", opts);
 };
 const day = (opts) => {
-	return { type: "day" };
+	return withOpts("day", opts);
 };
 const object = (opts) => {
-	return { type: "obj" };
+	return withOpts("obj", opts);
 };
 const array = (opts) => {
-	return { type: "array" };
+	return withOpts("array", opts);
 };
 const belongsTo = (opts) => {
 	return { type: () => {
-		return { type: "belongsTo" };
+		return withOpts("belongsTo", opts);
 	} };
 };
 

package/dist/{query-type-Dx5ZCv5N.d.ts → query-type-B0L3hwCo.d.ts}

@@ -16,7 +16,7 @@ type BaseOpts = {
 type FieldEntry = TypedField<string, any, any>;
 type InferSimpleFieldEntry<T extends FieldEntry> = T extends TypedField<any, infer X, infer Opts> ? Opts extends {
   optional: true;
-} ? X | null | "yes" : X : never;
+} ? X | null : X : never;
 //#endregion
 //#region src/models/_desc.d.ts
 type ModelDesc<TName extends string, TFields extends FieldDesc, TRelations extends RelationsDesc, TKey extends (keyof TFields & string)[]> = {
@@ -165,7 +165,7 @@ type ExtractRelQueryArray<M extends AnyDesc, TMap extends ModelMap, Q extends Re
 type InferHasMany<M extends AnyDesc, TMap extends ModelMap, QM extends HasManyQuery<M, TMap>> = QM extends {
   type: "count";
 } ? number : QM extends {
-  type: "exist";
+  type: "exists";
 } ? boolean : QM extends {
   type: "first";
 } ? InferModelQuery<M, EnsureModelQuery<QM>, TMap> | null : InferModelQuery<M, EnsureModelQuery<QM>, TMap>[];

package/dist/{store-B6JWZnAO.d.ts → store-LSWKTuHv.d.ts}

@@ -1,9 +1,36 @@
-import { ModelDesc, ModelQuery, RelationEntry, TypedField } from "./query-type-Dx5ZCv5N.js";
-import { AccountId, AccountOnboardingStepId, ActiveTimeTrackerId, ActivityId, AffiliateCodeId, AppId, AppInstallationId, AttachmentId, CardId, CardPresetId, CardSubscriptionId, CardUpvoteId, DeckId, DeckSubscriptionId, DiscordGuildId, DiscordMemberId, DiscordProjectNotificationId, DiscordSlashCommandId, FileId, IntegrationId, InvoiceId, MilestoneId, PinnedMilestoneId, ProjectId, ProjectSelectionId, ProjectTagId, QueueEntryId, QueueSelectionId, ReleaseId, ResolvableEntryId, ResolvableEntryReactionId, ResolvableId, SavedSearchId, SprintConfigId, SprintId, TimeTrackingSegmentId, UserEmailId, UserId, UserInvitationId, UserInviteCodeId, UserReportEmailId, UserReportSettingId, UserReportTokenId, UserTagId, VisionBoardId, VisionBoardQueryId, WizardId, WorkflowItemId, modelMap$1 as modelMap } from "./index-DUBsesYl.js";
-import { BaseLoader, LoaderResult } from "./loader-types-Dp0CSVTf.js";
+import { ModelDesc, ModelQuery, RelationEntry, TypedField } from "./query-type-B0L3hwCo.js";
+import { AccountId, AccountOnboardingStepId, ActiveTimeTrackerId, ActivityId, AffiliateCodeId, AppId, AppInstallationId, AttachmentId, CardId, CardPresetId, CardSubscriptionId, CardUpvoteId, DeckId, DeckSubscriptionId, DiscordGuildId, DiscordMemberId, DiscordProjectNotificationId, DiscordSlashCommandId, FileId, IntegrationId, InvoiceId, MilestoneId, PinnedMilestoneId, ProjectId, ProjectSelectionId, ProjectTagId, QueueEntryId, QueueSelectionId, ReleaseId, ResolvableEntryId, ResolvableEntryReactionId, ResolvableId, SavedSearchId, SprintConfigId, SprintId, TimeTrackingSegmentId, UserEmailId, UserId, UserInvitationId, UserInviteCodeId, UserReportEmailId, UserReportSettingId, UserReportTokenId, UserTagId, VisionBoardId, VisionBoardQueryId, WizardId, WorkflowItemId, modelMap$1 as modelMap } from "./index-obQtSRRg.js";
+import { BaseLoader, LoaderResult, MissingDataRequest } from "./loader-types-Y0OHlOEK.js";
 
+//#region src/_exploration/optimistic-manager.d.ts
+
+/**
+ * Represents a single optimistic update layer
+ * Contains field updates for one mutation
+ * Internal implementation - wrapped by ImmediateCache to provide full OptimisticUpdater interface
+ */
+declare class OptimisticLayer {
+  private data;
+  private affectedFields;
+  setField(model: string, id: string, field: string, value: any): void;
+  hasChanges(): boolean;
+  getAffectedFieldKeys(): Iterable<string>;
+  entries(): IterableIterator<[string, any]>;
+}
+/**
+ * Manages a stack of optimistic layers with O(1) lookups
+ *
+ * Design:
+ * - Maintains a stack of layers (one per in-flight mutation)
+ * - Rebuilds flattened view when layers added/removed for fast reads
+ * - Later layers override earlier ones (parallel updates supported)
+ * - Auto-cleanup via promise lifecycle
+ */
+//#endregion
 //#region src/_exploration/immediate-cache.d.ts
 type FieldMeta = {
+  state: "optimistic";
+} | {
   state: "fresh";
 } | {
   state: "dirty";
@@ -13,21 +40,58 @@ interface FieldCache<T = any> {
   partKeys: string[];
   meta: FieldMeta;
 }
+type FieldLocation = {
+  model: string;
+  id: string;
+  field: string;
+  fieldKey: string;
+  type: "field" | "relation";
+  cache: FieldCache;
+};
 type ModelInstance = Map<string, FieldCache>;
 type ModelCache = Map<string, ModelInstance>;
+type FieldSub = () => void;
+/**
+ * Wrapper that provides full OptimisticUpdater interface
+ * Delegates writes to OptimisticLayer and reads to ImmediateCache
+ */
+declare class OptimisticUpdater {
+  private layer;
+  private cache;
+  constructor(layer: OptimisticLayer,
+  // OptimisticLayer from optimistic-manager
+  cache: ImmediateCache);
+  setField(model: string, id: string, field: string, value: any): void;
+  getField(model: string, id: string, field: string): FieldCache | undefined;
+}
 declare class ImmediateCache {
   cache: ModelCache;
-  partKeyToFields: Map<string, FieldCache<any>[]>;
+  partKeyToFields: Map<string, FieldLocation[]>;
+  private fieldSubscriptions;
+  private optimisticManager;
   private getInstanceKey;
   get(model: string, key: string, field: string): FieldCache | undefined;
+  subscribe(fieldKey: string, notifyFn: FieldSub): () => void;
   set(model: string, key: string, partialInstance: Record<string, {
     value: unknown;
     partKeys: string[];
-  }>, meta: FieldMeta): void;
-  setMetaByPartKeys(partKeys: string[], meta: FieldMeta): void;
+    type: "field" | "relation";
+  }>, meta: FieldMeta): FieldSub[];
+  markDirty(partKeys: string[]): MissingDataRequest[];
+  /**
+   * Create a new optimistic layer bound to a promise and apply updates
+   * The layer will be automatically removed when the promise settles
+   * @param promise - Promise to bind the layer lifecycle to
+   * @param updateFn - Function to apply optimistic updates to the layer
+   * @returns The updater object with both read and write capabilities
+   */
+  createOptimisticLayer(promise: Promise<any>, updateFn: (updater: OptimisticUpdater) => void): OptimisticUpdater;
 }
 //#endregion
 //#region src/_exploration/store.d.ts
+type QueryDep = {
+  keys: string[];
+};
 type ModelMap = typeof modelMap;
 declare class Store {
   private loader;
@@ -2556,7 +2620,10 @@ declare class Store {
       }>;
     }, ["itemId"]>;
   };
+  requestedRelationKeys: Map<string, QueryDep>;
   constructor(loader: BaseLoader);
+  subscribeToField(fieldKey: string, notifyFn: () => void): () => void;
+  invalidate(partKeyPatterns: string[]): void;
   loadData(model: keyof ModelMap, ids: string[], q: ModelQuery<any, any>, acceptDirty?: boolean, iteration?: number): LoaderResult;
   onLoaded(model: string, key: string, partialInstance: Record<string, unknown>): void;
   /**
@@ -2564,6 +2631,30 @@ declare class Store {
    * Accumulates missing requests in the missingRequests array
    */
   private checkQueryRecursive;
+  /**
+   * Execute a mutation with optimistic updates
+   *
+   * @example
+   * ```typescript
+   * await store.mutate(
+   *   () => api.updateCard('123', {title: 'New Title'}),
+   *   {
+   *     onMutate: (layer) => {
+   *       layer.setField('Card', '123', 'title', 'New Title');
+   *     },
+   *     onSuccess: () => {
+   *       // Optional: invalidate related queries
+   *       store.invalidate(['Card:123:title']);
+   *     }
+   *   }
+   * );
+   * ```
+   */
+  mutate<T>(mutationFn: () => Promise<T>, options?: {
+    onMutate?: (updater: OptimisticUpdater) => void;
+    onSuccess?: (data: T) => void;
+    onError?: (error: unknown) => void;
+  }): Promise<T>;
 }
 //#endregion
 export { Store };

package/package.json

@@ -1,20 +1,21 @@
 {
   "name": "@codecks/fetch",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Quickly create deeply nested queries for the Codecks API with advanced TypeScript support",
   "type": "module",
   "license": "MIT",
-  "homepage": "https://github.com/codecks-io/cdx-fetch#readme",
+  "homepage": "https://github.com/codecks-io/fetch#readme",
   "bugs": {
-    "url": "https://github.com/codecks-io/cdx-fetch/issues"
+    "url": "https://github.com/codecks-io/fetch/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/codecks-io/cdx-fetch.git"
+    "url": "git+https://github.com/codecks-io/fetch.git"
   },
   "author": "Daniel Berndt <daniel@codecks.io>",
   "files": [
-    "dist"
+    "dist",
+    "schema"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -31,7 +32,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && vite-node scripts/generate-schema-docs.ts",
     "format": "prettier --write .",
     "check-format": "prettier --check .",
     "dev": "tsdown --watch",