@treygrr/nuxt-airplane 0.1.2 → 0.2.0

package/dist/module.json

@@ -4,7 +4,7 @@
   "compatibility": {
     "nuxt": ">=4.0.0"
   },
-  "version": "0.1.2",
+  "version": "0.2.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/runtime/client.d.ts

@@ -21,6 +21,24 @@ export interface QuerySnapshot {
 export declare function humanize(name: string): string;
 /** `undefined`, `null` and `{}` all mean "no variables" and share a key. */
 export declare function queryKey(name: string, variables: unknown): string;
+/** A fresh placeholder id: `tmp-` plus a UUID. */
+export declare function newTempId(): string;
+/** Whether a value is an id minted by `tempId()`. */
+export declare function isTempId(value: unknown): value is string;
+/**
+ * Replaces, anywhere in `value`, every string that is a key of `ids` with its
+ * mapped id. Reports whether anything changed and which minted temp ids are
+ * still in there with no mapping.
+ */
+export declare function substituteTempIds<T>(value: T, ids: Record<string, string>): {
+    value: T;
+    replaced: boolean;
+    unresolved: string[];
+};
+/** A mutation about to be sent still carries a temp id the server never assigned. */
+export declare class UnresolvedTempIdError extends Error {
+    name: string;
+}
 export type AirplaneClient = ReturnType<typeof createAirplaneClient>;
 export declare function createAirplaneClient(options: AirplaneClientOptions): {
     db: import("./types.js").AirplaneDexie;
@@ -192,6 +210,7 @@ export declare function createAirplaneClient(options: AirplaneClientOptions): {
                 })[];
                 before?: unknown;
             }[] | undefined;
+            tempIds?: string[] | undefined;
         }[];
         readonly blocked: number;
         syncTotal: number;
@@ -218,6 +237,7 @@ export declare function createAirplaneClient(options: AirplaneClientOptions): {
     };
     refetchActive: (only?: Iterable<QueryName>) => Promise<void>;
     enqueue: (name: string, variables: unknown) => Promise<MutationRow>;
+    execute: <T = unknown>(name: string, variables: unknown) => Promise<T>;
     rollback: (id: number) => Promise<void>;
     retry: (id: number) => Promise<void>;
     sync: () => Promise<void>;

package/dist/runtime/client.js

@@ -13,6 +13,44 @@ export function queryKey(name, variables) {
   const normalized = variables && typeof variables === "object" && Object.keys(variables).length ? variables : null;
   return `${name}:${hash(normalized)}`;
 }
+const TEMP_ID_PREFIX = "tmp-";
+const TEMP_ID_RE = /^tmp-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+export function newTempId() {
+  const uuid = typeof crypto === "object" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+  return `${TEMP_ID_PREFIX}${uuid}`;
+}
+export function isTempId(value) {
+  return typeof value === "string" && TEMP_ID_RE.test(value);
+}
+export function substituteTempIds(value, ids) {
+  let replaced = false;
+  const unresolved = /* @__PURE__ */ new Set();
+  const walk = (v) => {
+    if (typeof v === "string") {
+      if (v in ids) {
+        replaced = true;
+        return ids[v];
+      }
+      if (isTempId(v)) unresolved.add(v);
+      return v;
+    }
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === "object" && Object.getPrototypeOf(v) === Object.prototype) {
+      const out = {};
+      for (const [k, item] of Object.entries(v)) out[k] = walk(item);
+      return out;
+    }
+    return v;
+  };
+  const next = walk(value);
+  return { value: replaced ? next : value, replaced, unresolved: [...unresolved] };
+}
+export class UnresolvedTempIdError extends Error {
+  name = "UnresolvedTempIdError";
+}
 export function createAirplaneClient(options) {
   const db = createDb(options.dbName, options.stores.stores, options.stores.version);
   const { documents, mutationHandlers, queryHandlers } = options;
@@ -219,10 +257,34 @@ export function createAirplaneClient(options) {
     const h = mutationHandler(row.document);
     if (!h?.apply) return;
     const invalidated = /* @__PURE__ */ new Set();
-    const { undo } = await withUndoLog(db, () => h.apply({ db, cache: createCacheApi(invalidated), variables: row.variables }));
-    await db.mutations.update(row.id, { undo });
+    const tempIds = [...row.tempIds ?? []];
+    let minted = 0;
+    const tempId = () => (tempIds[minted] ??= newTempId(), tempIds[minted++]);
+    const { undo } = await withUndoLog(db, () => h.apply({ db, cache: createCacheApi(invalidated), variables: row.variables, tempId }));
+    await db.mutations.update(row.id, { undo, tempIds });
     if (!rebase && invalidated.size) await refetchActive(invalidated);
   }
+  const TEMP_IDS_KEY = "tempIds";
+  const TEMP_IDS_MAX = 1e3;
+  async function readTempIds() {
+    const raw = (await db.meta.get(TEMP_IDS_KEY))?.value;
+    return raw ? JSON.parse(raw) : {};
+  }
+  async function resolveTempId(tempId, id) {
+    const entries = Object.entries(await readTempIds()).filter(([key]) => key !== tempId);
+    entries.push([tempId, id]);
+    await db.meta.put({ key: TEMP_IDS_KEY, value: JSON.stringify(Object.fromEntries(entries.slice(-TEMP_IDS_MAX))) });
+  }
+  function reconcileContext(variables, tempIds = []) {
+    return { db, cache: createCacheApi(), variables, tempIds, resolve: resolveTempId };
+  }
+  async function outboundVariables(name, variables) {
+    const { value, unresolved } = substituteTempIds(variables, await readTempIds());
+    if (unresolved.length) {
+      throw new UnresolvedTempIdError(`[nuxt-airplane] "${name}" references the temp id "${unresolved[0]}" which has no server id yet: the mutation that created it has not been accepted, or its reconcile handler did not call resolve().`);
+    }
+    return value;
+  }
   async function rebasePending() {
     const queue = await db.mutations.orderBy("createdAt").toArray();
     for (const row of queue) await applyMutation(row, { rebase: true });
@@ -307,15 +369,17 @@ export function createAirplaneClient(options) {
       for (const row of queue) {
         await db.mutations.update(row.id, { status: "syncing" });
         try {
-          const result = await request(row.document, row.variables);
+          const variables = await outboundVariables(row.document, row.variables);
+          if (variables !== row.variables) await db.mutations.update(row.id, { variables });
+          const result = await request(row.document, variables);
           const h = mutationHandler(row.document);
-          await h?.reconcile?.({ db, cache: createCacheApi(), variables: row.variables }, result);
+          await h?.reconcile?.(reconcileContext(variables, row.tempIds), result);
           if (h?.refetch) h.refetch.forEach((n) => refetch.add(n));
           else refetchAll = true;
           await db.mutations.delete(row.id);
           state.syncCount++;
         } catch (error) {
-          if (error instanceof GraphQLRequestError) {
+          if (error instanceof GraphQLRequestError || error instanceof UnresolvedTempIdError) {
             await db.mutations.update(row.id, { status: "failed", error: error.message });
             if (stopOnFailure) break;
             continue;
@@ -330,6 +394,19 @@ export function createAirplaneClient(options) {
     }
     if (state.syncCount) await refetchActive(refetchAll ? void 0 : refetch);
   }
+  async function execute(name, variables) {
+    if (document(name).kind !== "mutation") throw new Error(`[nuxt-airplane] "${name}" is not a mutation`);
+    await ready;
+    if (!state.online) throw new Error(`[nuxt-airplane] Cannot send "${name}" while offline`);
+    await sync();
+    if (state.online && (await sendable()).length) await sync();
+    const outbound = await outboundVariables(name, variables);
+    const result = await request(name, outbound);
+    const h = mutationHandler(name);
+    await h?.reconcile?.(reconcileContext(outbound), result);
+    await refetchActive(h?.refetch);
+    return result;
+  }
   async function clear() {
     await db.transaction("rw", db.tables, async () => {
       for (const table of db.tables) await table.clear();
@@ -348,6 +425,7 @@ export function createAirplaneClient(options) {
     watchQuery,
     refetchActive,
     enqueue,
+    execute,
     rollback,
     retry,
     sync,

package/dist/runtime/composables/useMutation.d.ts

@@ -1,14 +1,31 @@
 import { type Ref } from 'vue';
-import type { MutationName, MutationRow, MutationVariables } from '../types.js';
-export interface UseMutationReturn<V> {
+import type { MutationName, MutationResult, MutationRow, MutationVariables } from '../types.js';
+export interface UseMutationOptions {
+    /**
+     * `false` sends the mutation directly instead of queuing it: `mutate`
+     * resolves with the server's data, runs no `apply`, and rejects while
+     * offline. For mutations that cannot wait in the outbox, such as a checkout
+     * or anything whose response the UI needs. Default `true`.
+     */
+    queue?: boolean;
+}
+export interface UseMutationReturn<V, R = MutationRow> {
     /**
      * Applies the mutation to the local cache and queues it for the server.
      * Resolves with the outbox entry as soon as the change is visible locally;
      * the request itself is sent in the background by the sync loop.
+     *
+     * With `queue: false` it sends the request now and resolves with the data
+     * the server returned.
      */
-    mutate: (variables: V) => Promise<MutationRow>;
-    /** `true` while the local `apply` handler runs. */
+    mutate: (variables: V) => Promise<R>;
+    /** `true` while the local `apply` handler runs, or while the request is in flight with `queue: false`. */
     loading: Ref<boolean>;
     error: Ref<Error | null>;
 }
-export declare function useMutation<N extends MutationName>(name: N): UseMutationReturn<MutationVariables<N>>;
+export declare function useMutation<N extends MutationName>(name: N, options?: UseMutationOptions & {
+    queue?: true;
+}): UseMutationReturn<MutationVariables<N>>;
+export declare function useMutation<N extends MutationName>(name: N, options: UseMutationOptions & {
+    queue: false;
+}): UseMutationReturn<MutationVariables<N>, MutationResult<N>>;

package/dist/runtime/composables/useMutation.js

@@ -1,15 +1,16 @@
 import { ref, shallowRef } from "vue";
 import { useAirplane } from "./useAirplane.js";
-export function useMutation(name) {
+export function useMutation(name, options = {}) {
   const loading = ref(false);
   const error = shallowRef(null);
   const client = useAirplane();
+  const queue = options.queue ?? true;
   async function mutate(variables) {
     if (!client) throw new Error("[nuxt-airplane] Mutations can only run on the client");
     loading.value = true;
     error.value = null;
     try {
-      return await client.enqueue(name, variables);
+      return queue ? await client.enqueue(name, variables) : await client.execute(name, variables);
     } catch (e) {
       error.value = e;
       throw e;

package/dist/runtime/plugin.client.d.ts

@@ -170,6 +170,7 @@ declare const _default: import("#app").Plugin<{
                     })[];
                     before?: unknown;
                 }[] | undefined;
+                tempIds?: string[] | undefined;
             }[];
             readonly blocked: number;
             syncTotal: number;
@@ -196,6 +197,7 @@ declare const _default: import("#app").Plugin<{
         };
         refetchActive: (only?: Iterable<import("./types.js").QueryName>) => Promise<void>;
         enqueue: (name: string, variables: unknown) => Promise<import("./types.js").MutationRow>;
+        execute: <T = unknown>(name: string, variables: unknown) => Promise<T>;
         rollback: (id: number) => Promise<void>;
         retry: (id: number) => Promise<void>;
         sync: () => Promise<void>;
@@ -377,6 +379,7 @@ declare const _default: import("#app").Plugin<{
                     })[];
                     before?: unknown;
                 }[] | undefined;
+                tempIds?: string[] | undefined;
             }[];
             readonly blocked: number;
             syncTotal: number;
@@ -403,6 +406,7 @@ declare const _default: import("#app").Plugin<{
         };
         refetchActive: (only?: Iterable<import("./types.js").QueryName>) => Promise<void>;
         enqueue: (name: string, variables: unknown) => Promise<import("./types.js").MutationRow>;
+        execute: <T = unknown>(name: string, variables: unknown) => Promise<T>;
         rollback: (id: number) => Promise<void>;
         retry: (id: number) => Promise<void>;
         sync: () => Promise<void>;

package/dist/runtime/types.d.ts

@@ -72,6 +72,11 @@ export interface MutationRow {
     error?: string;
     /** Writes made by `apply`, oldest first, used to roll the mutation back. */
     undo?: UndoEntry[];
+    /**
+     * Ids handed out by `tempId()` while `apply` ran, in call order. A re-apply
+     * (rebase) hands out the same ones so the local rows keep their ids.
+     */
+    tempIds?: string[];
 }
 /** Module bookkeeping, e.g. the cache key the data was written under. */
 export interface MetaRow {
@@ -103,6 +108,28 @@ export interface HandlerContext<V = unknown> {
     cache: CacheApi;
     variables: V;
 }
+/** What `apply` receives: the handler context plus a way to mint placeholder ids. */
+export interface ApplyContext<V = unknown> extends HandlerContext<V> {
+    /**
+     * A placeholder id for a row the server will assign an id to. Mutations
+     * queued later that reference it are rewritten with the real id before they
+     * are sent, once `reconcile` has called `resolve`. The same ids come back,
+     * in the same order, when `apply` is re-run on fresh server data.
+     */
+    tempId: () => string;
+}
+/** What `reconcile` receives: the handler context plus `resolve`. */
+export interface ReconcileContext<V = unknown> extends HandlerContext<V> {
+    /** The ids `apply` minted with `tempId()`, in call order; empty for a mutation sent with `execute`. */
+    tempIds: string[];
+    /**
+     * Records that the placeholder `tempId` stands for the server-assigned `id`.
+     * Every queued mutation whose variables mention `tempId` is sent with `id`
+     * instead, also one queued after the outbox drained with an id a component
+     * still held. The last 1000 mappings are kept.
+     */
+    resolve: (tempId: string, id: string) => Promise<void>;
+}
 export interface MutationHandler<N extends MutationName = MutationName> {
     /**
      * A human-readable summary for the pending list, e.g. "Archive North Warehouse".
@@ -114,9 +141,13 @@ export interface MutationHandler<N extends MutationName = MutationName> {
      * Runs as soon as the mutation is queued, so the UI reflects it immediately.
      * It runs inside a Dexie transaction and every write is recorded for rollback.
      */
-    apply?: (ctx: HandlerContext<MutationVariables<N>>) => unknown;
-    /** Runs with the server's response once the mutation has been sent. */
-    reconcile?: (ctx: HandlerContext<MutationVariables<N>>, result: MutationResult<N>) => unknown;
+    apply?: (ctx: ApplyContext<MutationVariables<N>>) => unknown;
+    /**
+     * Runs with the server's response once the mutation has been sent. Merge
+     * server-assigned values into the local data here and call `resolve` for
+     * every id minted with `tempId()`.
+     */
+    reconcile?: (ctx: ReconcileContext<MutationVariables<N>>, result: MutationResult<N>) => unknown;
     /**
      * Runs when a queued mutation is rolled back. When omitted the writes made
      * by `apply` are undone from the recorded log instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treygrr/nuxt-airplane",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Airplane mode for your GraphQL app: typed composables from your .gql files, an IndexedDB cache and a mutation queue that lands when you are back online.",
   "keywords": [
     "nuxt",