@codecks/fetch 0.1.5 → 0.1.7

package/dist/{store-B6JWZnAO.d.ts → store-BvEJzUVp.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-BqQ9oX_U.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-k-KPWV9R.js";
+import { BaseLoader, LoaderResult, MissingDataRequest } from "./loader-types-fd5tV0FD.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;
@@ -834,6 +898,7 @@ declare class Store {
       }>;
       attachments: RelationEntry<"attachment", {
         readonly type: "hasMany";
+        readonly fkAsArray: true;
       }>;
       diffs: RelationEntry<"cardHistory", {
         readonly type: "hasMany";
@@ -846,15 +911,19 @@ declare class Store {
       }>;
       childCards: RelationEntry<"card", {
         readonly type: "hasMany";
+        readonly fkAsArray: true;
       }>;
       inDeps: RelationEntry<"card", {
         readonly type: "hasMany";
+        readonly fkAsArray: true;
       }>;
       outDeps: RelationEntry<"card", {
         readonly type: "hasMany";
+        readonly fkAsArray: true;
       }>;
       cardReferences: RelationEntry<"card", {
         readonly type: "hasMany";
+        readonly fkAsArray: true;
       }>;
       upvotes: RelationEntry<"cardUpvote", {
         readonly type: "hasMany";
@@ -2550,13 +2619,18 @@ declare class Store {
       }>;
       inDeps: RelationEntry<"workflowItem", {
         readonly type: "hasMany";
+        readonly fkAsArray: true;
       }>;
       outDeps: RelationEntry<"workflowItem", {
         readonly type: "hasMany";
+        readonly fkAsArray: true;
       }>;
     }, ["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 +2638,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,6 +1,6 @@
 {
   "name": "@codecks/fetch",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Quickly create deeply nested queries for the Codecks API with advanced TypeScript support",
   "type": "module",
   "license": "MIT",
@@ -14,7 +14,8 @@
   },
   "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",

package/schema/models/account.md

@@ -0,0 +1,104 @@
+# account
+
+Key: `id`
+
+## Fields
+
+- `id`: string
+- `subdomain`: string
+- `name`: string
+- `billingName`: string, optional
+- `billingLine1`: string, optional
+- `billingLine2`: string, optional
+- `billingZip`: string, optional
+- `billingCity`: string, optional
+- `billingCountryCode`: string, optional
+- `billingEmail`: string, optional
+- `netGiftAmount`: number
+- `persona`: string, optional
+- `createdAt`: Date (ISO string)
+- `disabledAt`: Date (ISO string), optional
+- `totalMediaByteUsage`: bigint
+- `isDisabled`: string
+- `milestonesEnabled`: string
+- `sprintsEnabled`: string
+- `priorityLabels`: object
+- `effortScale`: object
+- `statusChangeDurations`: object
+- `activeFeatureFlags`: object
+- `timeTrackingMode`: string
+- `maxTimeTrackingSegmentMsDuration`: number
+- `timeTrackingSwimLaneInfo`: boolean
+- `workdays`: string
+- `workflowMode`: string
+- `isLearning`: boolean
+- `isNonProfit`: boolean
+- `dependenciesEnabled`: boolean
+- `maxHandSlotCount`: number
+- `seats`: number
+- `activeProjectCount`: number
+- `billingType`: string
+- `allowInheritHeroCover`: boolean
+- `attachmentCoverMode`: string
+- `staffPermission`: string
+- `offeringTrial`: boolean
+- `coupon`: object, optional
+- `hideCompletedCardCountForDecks`: boolean
+- `visionBoardEnabled`: boolean
+- `fallbackEffort`: number
+- `timelineScaleType`: string
+- `startWeekday`: string
+- `disabledById`: string (foreign key ID) → user, optional
+
+## Relations
+
+### belongsTo
+
+- `disabledBy` → [user](user.md) (via `disabledById`)
+
+### hasOne
+
+- `githubIntegration` → [integration](integration.md)
+- `slackIntegration` → [integration](integration.md)
+- `stripeAccountSync` → [stripeAccountSync](stripeAccountSync.md)
+- `accountOnboarding` → [accountOnboarding](accountOnboarding.md)
+
+### hasMany
+
+- `cards` → [card](card.md)
+- `invoices` → [invoice](invoice.md)
+- `cardPresets` → [cardPreset](cardPreset.md)
+- `attachments` → [attachment](attachment.md)
+- `discordGuilds` → [discordGuild](discordGuild.md)
+- `timeTrackingSegments` → [timeTrackingSegment](timeTrackingSegment.md)
+- `workflowItems` → [workflowItem](workflowItem.md)
+- `deckAssignments` → [deckAssignment](deckAssignment.md)
+- `assigneeAssignments` → [assigneeAssignment](assigneeAssignment.md)
+- `assigneeDeckAssignments` → [assigneeDeckAssignment](assigneeDeckAssignment.md)
+- `wizards` → [wizard](wizard.md)
+- `milestones` → [milestone](milestone.md)
+- `sprints` → [sprint](sprint.md)
+- `sprintConfigs` → [sprintConfig](sprintConfig.md)
+- `handCards` → [handCard](handCard.md)
+- `resolvables` → [resolvable](resolvable.md)
+- `cardUpvotes` → [cardUpvote](cardUpvote.md)
+- `resolvableParticipants` → [resolvableParticipant](resolvableParticipant.md)
+- `userReportSettings` → [userReportSetting](userReportSetting.md)
+- `cardOrders` → [cardOrder](cardOrder.md)
+- `accountUserAchievements` → [accountUserAchievement](accountUserAchievement.md)
+- `userInviteCodes` → [userInviteCode](userInviteCode.md)
+- `visionBoards` → [visionBoard](visionBoard.md)
+- `deckSubscriptions` → [deckSubscription](deckSubscription.md)
+- `appInstallations` → [appInstallation](appInstallation.md)
+- `files` → [file](file.md)
+- `decks` → [deck](deck.md)
+- `queueEntries` → [queueEntry](queueEntry.md)
+- `visionBoardQueries` → [visionBoardQuery](visionBoardQuery.md)
+- `anyDecks` → [deck](deck.md)
+- `projects` → [project](project.md)
+- `archivedProjects` → [project](project.md)
+- `anyProjects` → [project](project.md)
+- `roles` → [accountRole](accountRole.md)
+- `invitations` → [userInvitation](userInvitation.md)
+- `affiliateCodes` → [affiliateCode](affiliateCode.md)
+- `activities` → [activity](activity.md)

package/schema/models/accountOnboarding.md

@@ -0,0 +1,15 @@
+# accountOnboarding
+
+Key: `accountId`
+
+## Fields
+
+- `variants`: array
+- `steps`: object
+- `accountId`: string (foreign key ID) → account
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)

package/schema/models/accountOnboardingStep.md

@@ -0,0 +1,14 @@
+# accountOnboardingStep
+
+Key: `key`
+
+## Fields
+
+- `key`: string
+- `title`: string
+- `description`: string
+- `chapter`: string
+- `sortValue`: string
+- `variants`: array
+- `xp`: number
+- `milestone`: string

package/schema/models/accountRole.md

@@ -0,0 +1,19 @@
+# accountRole
+
+Key: `accountId`, `userId`
+
+## Fields
+
+- `role`: string
+- `createdAt`: Date (ISO string)
+- `lastChangedAt`: Date (ISO string)
+- `roleAsPrio`: number
+- `userId`: string (foreign key ID) → user
+- `accountId`: string (foreign key ID) → account
+
+## Relations
+
+### belongsTo
+
+- `user` → [user](user.md) (via `userId`)
+- `account` → [account](account.md) (via `accountId`)

package/schema/models/accountUserAchievement.md

@@ -0,0 +1,17 @@
+# accountUserAchievement
+
+Key: `accountId`, `userId`, `key`
+
+## Fields
+
+- `value`: object
+- `context`: object
+- `accountId`: string (foreign key ID) → account
+- `userId`: string (foreign key ID) → user
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)
+- `user` → [user](user.md) (via `userId`)

package/schema/models/accountUserSetting.md

@@ -0,0 +1,20 @@
+# accountUserSetting
+
+Key: `accountId`, `userId`
+
+## Fields
+
+- `wantsWeeklyDigestMail`: boolean
+- `timelineScaleTypeOverwrite`: string
+- `startWeekdayOverwrite`: string
+- `accountId`: string (foreign key ID) → account
+- `userId`: string (foreign key ID) → user
+- `inboxDeckId`: string (foreign key ID) → deck
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)
+- `user` → [user](user.md) (via `userId`)
+- `inboxDeck` → [deck](deck.md) (via `inboxDeckId`)

package/schema/models/activeTimeTracker.md

@@ -0,0 +1,19 @@
+# activeTimeTracker
+
+Key: `id`
+
+## Fields
+
+- `id`: string
+- `createdAt`: Date (ISO string)
+- `cardId`: string (foreign key ID) → card
+- `userId`: string (foreign key ID) → user
+- `accountId`: string (foreign key ID) → account
+
+## Relations
+
+### belongsTo
+
+- `card` → [card](card.md) (via `cardId`)
+- `user` → [user](user.md) (via `userId`)
+- `account` → [account](account.md) (via `accountId`)

package/schema/models/activity.md

@@ -0,0 +1,30 @@
+# activity
+
+Key: `id`
+
+## Fields
+
+- `id`: string
+- `type`: string
+- `data`: object
+- `isRemovedFromDeckEntry`: boolean
+- `isRemovedFromMilestoneEntry`: boolean
+- `isRemovedFromSprintEntry`: boolean
+- `createdAt`: Date (ISO string)
+- `cardId`: string (foreign key ID) → card
+- `deckId`: string (foreign key ID) → deck
+- `projectId`: string (foreign key ID) → project
+- `milestoneId`: string (foreign key ID) → milestone
+- `sprintId`: string (foreign key ID) → sprint
+- `changerId`: string (foreign key ID) → user
+
+## Relations
+
+### belongsTo
+
+- `card` → [card](card.md) (via `cardId`)
+- `deck` → [deck](deck.md) (via `deckId`)
+- `project` → [project](project.md) (via `projectId`)
+- `milestone` → [milestone](milestone.md) (via `milestoneId`)
+- `sprint` → [sprint](sprint.md) (via `sprintId`)
+- `changer` → [user](user.md) (via `changerId`)

package/schema/models/affiliateCode.md

@@ -0,0 +1,30 @@
+# affiliateCode
+
+Key: `id`
+
+## Fields
+
+- `id`: string
+- `code`: string
+- `vanityUrl`: string
+- `message`: string
+- `label`: string
+- `isDisabled`: string
+- `isDeleted`: string
+- `validUntil`: string
+- `remainingRedemptions`: string
+- `reward`: object
+- `createdAt`: Date (ISO string)
+- `accountId`: string (foreign key ID) → account
+- `creatorId`: string (foreign key ID) → user
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)
+- `creator` → [user](user.md) (via `creatorId`)
+
+### hasMany
+
+- `stats` → [affiliateCodeStat](affiliateCodeStat.md)

package/schema/models/affiliateCodeStat.md

@@ -0,0 +1,19 @@
+# affiliateCodeStat
+
+Key: `affiliateCodeId`, `month`
+
+## Fields
+
+- `month`: number
+- `year`: number
+- `visits`: number
+- `newVisitors`: number
+- `signups`: number
+- `revenue`: number
+- `affiliateCodeId`: string (foreign key ID) → affiliateCode
+
+## Relations
+
+### belongsTo
+
+- `affiliateCode` → [affiliateCode](affiliateCode.md) (via `affiliateCodeId`)

package/schema/models/app.md

@@ -0,0 +1,10 @@
+# app
+
+Key: `id`
+
+## Fields
+
+- `id`: string
+- `name`: string
+- `createdAt`: Date (ISO string)
+- `payload`: object

package/schema/models/appInstallation.md

@@ -0,0 +1,19 @@
+# appInstallation
+
+Key: `id`
+
+## Fields
+
+- `id`: string
+- `createdAt`: Date (ISO string)
+- `accountId`: string (foreign key ID) → account
+- `appId`: string (foreign key ID) → app
+- `installerId`: string (foreign key ID) → user
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)
+- `app` → [app](app.md) (via `appId`)
+- `installer` → [user](user.md) (via `installerId`)

package/schema/models/assigneeAssignment.md

@@ -0,0 +1,18 @@
+# assigneeAssignment
+
+Key: `assigneeId`, `assignedById`
+
+## Fields
+
+- `lastAssignedAt`: Date (ISO string)
+- `accountId`: string (foreign key ID) → account
+- `assigneeId`: string (foreign key ID) → user
+- `assignedById`: string (foreign key ID) → user
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)
+- `assignee` → [user](user.md) (via `assigneeId`)
+- `assignedBy` → [user](user.md) (via `assignedById`)

package/schema/models/assigneeDeckAssignment.md

@@ -0,0 +1,20 @@
+# assigneeDeckAssignment
+
+Key: `assigneeId`, `assignedById`, `deckId`
+
+## Fields
+
+- `lastAssignedAt`: Date (ISO string)
+- `accountId`: string (foreign key ID) → account
+- `deckId`: string (foreign key ID) → deck
+- `assigneeId`: string (foreign key ID) → user
+- `assignedById`: string (foreign key ID) → user
+
+## Relations
+
+### belongsTo
+
+- `account` → [account](account.md) (via `accountId`)
+- `deck` → [deck](deck.md) (via `deckId`)
+- `assignee` → [user](user.md) (via `assigneeId`)
+- `assignedBy` → [user](user.md) (via `assignedById`)

package/schema/models/attachment.md

@@ -0,0 +1,23 @@
+# attachment
+
+Key: `id`
+
+## Fields
+
+- `id`: string
+- `content`: string
+- `title`: string
+- `createdAt`: Date (ISO string)
+- `fileId`: string (foreign key ID) → file
+- `cardId`: string (foreign key ID) → card
+- `accountId`: string (foreign key ID) → account
+- `creatorId`: string (foreign key ID) → user
+
+## Relations
+
+### belongsTo
+
+- `file` → [file](file.md) (via `fileId`)
+- `card` → [card](card.md) (via `cardId`)
+- `account` → [account](account.md) (via `accountId`)
+- `creator` → [user](user.md) (via `creatorId`)

package/schema/models/autoFinishedTimeTrackingSegment.md

@@ -0,0 +1,20 @@
+# autoFinishedTimeTrackingSegment
+
+Key: `userId`, `accountId`
+
+## Fields
+
+- `createdAt`: Date (ISO string)
+- `userId`: string (foreign key ID) → user
+- `accountId`: string (foreign key ID) → account
+- `cardId`: string (foreign key ID) → card
+- `timeTrackingSegmentId`: string (foreign key ID) → timeTrackingSegment
+
+## Relations
+
+### belongsTo
+
+- `user` → [user](user.md) (via `userId`)
+- `account` → [account](account.md) (via `accountId`)
+- `card` → [card](card.md) (via `cardId`)
+- `timeTrackingSegment` → [timeTrackingSegment](timeTrackingSegment.md) (via `timeTrackingSegmentId`)