@treygrr/nuxt-airplane 0.1.1 → 0.2.0

package/README.md

@@ -36,6 +36,7 @@ export default defineNuxtConfig({
 | `documents` | `['**/*.gql', '**/*.graphql']` | Globs (relative to `srcDir`) of the files holding your operations. |
 | `handlersDir` | `airplane` | Directory (relative to `srcDir`) scanned for mutation handler files. |
 | `dbName` | `nuxt-airplane` | IndexedDB database name. |
+| `stopOnFailure` | `true` | A failed mutation holds back the ones queued after it until retried or rolled back (`useSync().blocked` counts them). |
 | `cacheKey` | – | Deploy key (git SHA, build id). A change wipes cached data on next load, outbox kept; a hash of your documents is always mixed in. `NUXT_PUBLIC_AIRPLANE_CACHE_KEY` overrides it. |
 | `codegen` | `{}` | Extra config for the `typescript` / `typescript-operations` codegen plugins. |
 
@@ -152,8 +153,9 @@ const { online, syncing, synced, pending, syncTotal, syncCount, lastError, sync,
 
 - `pending` lists the queued mutations oldest first, each with a human-readable `description` (from the handler's `describe` hook, or the humanized document name), its variables and status.
 - `rollback(id)` undoes a queued mutation locally and drops it from the queue. Mutations queued after it are re-applied on top of the restored data.
-- A mutation the server rejects is marked `failed` and left in the queue; `retry(id)` or `rollback(id)` it.
+- A mutation the server rejects is marked `failed` and left in the queue, and the mutations queued after it wait (`blocked`) until you `retry(id)` or `rollback(id)` it; set `stopOnFailure: false` to keep sending past failures.
 - A network failure stops the batch and keeps everything queued; the next `online` event (or `sync()`) resumes it.
+- Tabs share the database; a Web Lock makes sure only one of them sends the queue at a time.
 - `goOffline()` holds the client offline whatever the network says: queries serve the cache only and mutations stay queued. `goOnline()` releases it and syncs. `online` reflects the effective state; `networkOnline` and `forcedOffline` expose the two inputs. Handy for a "work offline" switch or for testing.
 
 ## Security

package/dist/module.d.mts

@@ -25,6 +25,13 @@ interface ModuleOptions {
      * Overridable at runtime with `NUXT_PUBLIC_AIRPLANE_CACHE_KEY`.
      */
     cacheKey?: string;
+    /**
+     * When a mutation is rejected by the server, hold back the mutations queued
+     * after it until it is retried or rolled back, so the outbox keeps its
+     * order (an item added to a site that was never created would fail too).
+     * Set to `false` to skip failed mutations and keep sending the rest.
+     */
+    stopOnFailure: boolean;
     /** Extra options passed to the `typescript` / `typescript-operations` codegen plugins. */
     codegen: Record<string, unknown>;
 }

package/dist/module.json

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

package/dist/module.mjs

@@ -1,9 +1,9 @@
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
 import { join, dirname, resolve, sep, basename } from 'node:path';
 import { defineNuxtModule, createResolver, useLogger, addTemplate, addTypeTemplate, addImportsDir, addPlugin, updateTemplates } from '@nuxt/kit';
 import { hash } from 'ohash';
 import { glob } from 'tinyglobby';
 import { existsSync } from 'node:fs';
-import { readFile, mkdir, writeFile } from 'node:fs/promises';
 import { codegen } from '@graphql-codegen/core';
 import * as typescriptPlugin from '@graphql-codegen/typescript';
 import * as typescriptOperationsPlugin from '@graphql-codegen/typescript-operations';
@@ -154,6 +154,39 @@ async function generateTypes(schema, docs, config = {}) {
   ].join("\n");
 }
 
+const DEFINE_HELPERS = [
+  "defineMutationHandler",
+  "defineMutationHandlers",
+  "defineQueryHandler",
+  "defineQueryHandlers",
+  "defineAirplaneStores",
+  "defineAirplaneRequest"
+];
+const WRAP_HINT = "Wrap it in defineMutationHandlers(...) / defineQueryHandler(name, ...) / defineAirplaneStores(...) / defineAirplaneRequest(...), or export it from outside the handlers directory.";
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|\s)\/\/.*$/gm, "$1");
+}
+function findUntaggedDefaultExport(source) {
+  const code = stripComments(source);
+  const match = /\bexport\s+default\s+(?:await\s+)?/.exec(code);
+  if (!match) return null;
+  const rest = code.slice(match.index + match[0].length).trimStart();
+  if (rest.startsWith("{")) return { reason: "an object literal" };
+  if (rest.startsWith("[")) return { reason: "an array literal" };
+  if (/^(?:async\s+)?function\b/.test(rest)) return { reason: "a function" };
+  if (/^class\b/.test(rest)) return { reason: "a class" };
+  if (/^new\b/.test(rest)) return { reason: "a `new` expression" };
+  if (/^(?:async\s+)?(?:\([^)]*\)|[\w$]+)\s*=>/.test(rest)) return { reason: "an arrow function" };
+  if (/^(?:['"`\d]|true\b|false\b|null\b|undefined\b)/.test(rest)) return { reason: "a literal value" };
+  const call = /^([\w$]+(?:\s*\.\s*[\w$]+)*)\s*(?:<[^()]*>\s*)?\(/.exec(rest);
+  if (call) {
+    const callee = call[1].replace(/\s+/g, "");
+    if (DEFINE_HELPERS.includes(callee)) return null;
+    return { reason: `a call to \`${callee}()\`` };
+  }
+  return null;
+}
+
 const module$1 = defineNuxtModule({
   meta: {
     name: "nuxt-airplane",
@@ -165,6 +198,7 @@ const module$1 = defineNuxtModule({
     documents: ["**/*.gql", "**/*.graphql"],
     handlersDir: "airplane",
     dbName: "nuxt-airplane",
+    stopOnFailure: true,
     codegen: {}
   },
   async setup(options, nuxt) {
@@ -176,7 +210,8 @@ const module$1 = defineNuxtModule({
       endpoint: options.endpoint,
       dbName: options.dbName,
       cacheKey: options.cacheKey ?? "",
-      headers: options.headers ?? {}
+      headers: options.headers ?? {},
+      stopOnFailure: options.stopOnFailure
     };
     nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
     nuxt.options.vite.optimizeDeps ||= {};
@@ -215,6 +250,16 @@ const module$1 = defineNuxtModule({
       write: true,
       getContents: async () => {
         const files = await handlerFiles();
+        const offenders = [];
+        for (const file of files) {
+          const untagged = findUntaggedDefaultExport(await readFile(file, "utf8"));
+          if (untagged) offenders.push(`  ${file}: default export is ${untagged.reason}`);
+        }
+        if (offenders.length) {
+          throw new Error(`[nuxt-airplane] Files in the handlers directory must default-export the result of a define* helper:
+${offenders.join("\n")}
+${WRAP_HINT}`);
+        }
         const imports = files.map((file, i) => `import h${i} from ${JSON.stringify(file)}`);
         const list = files.map((_, i) => `h${i}`).join(", ");
         return `${imports.join("\n")}

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,7 +210,9 @@ export declare function createAirplaneClient(options: AirplaneClientOptions): {
                 })[];
                 before?: unknown;
             }[] | undefined;
+            tempIds?: string[] | undefined;
         }[];
+        readonly blocked: number;
         syncTotal: number;
         syncCount: number;
         lastError: string | null;
@@ -217,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,9 +13,48 @@ 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;
+  const stopOnFailure = options.stopOnFailure ?? true;
   const opened = db.open().catch(async (error) => {
     if (!["VersionError", "UpgradeError", "SchemaError"].includes(error.name)) throw error;
     console.warn(`[nuxt-airplane] Could not open "${options.dbName}" (${error.name}), recreating it. Bump the store version to migrate instead.`);
@@ -36,8 +75,11 @@ export function createAirplaneClient(options) {
       await clearCache();
     }
     if (stored !== cacheKey) await db.meta.put({ key: "cacheKey", value: cacheKey });
-    await db.mutations.where("status").equals("syncing").modify({ status: "pending" });
+    await requeueStuck();
   });
+  async function requeueStuck() {
+    await db.mutations.where("status").equals("syncing").modify({ status: "pending" });
+  }
   const state = reactive({
     /** What the browser reports; assumed online where `navigator.onLine` does not exist (Node, some webviews). */
     networkOnline: typeof navigator === "object" && typeof navigator.onLine === "boolean" ? navigator.onLine : true,
@@ -50,6 +92,12 @@ export function createAirplaneClient(options) {
     syncing: false,
     /** Mutations still waiting to be sent, oldest first. */
     pending: [],
+    /** Pending mutations held back because an older one failed; `0` with `stopOnFailure: false`. */
+    get blocked() {
+      if (!stopOnFailure) return 0;
+      const failed = this.pending.findIndex((m) => m.status === "failed");
+      return failed < 0 ? 0 : this.pending.slice(failed + 1).filter((m) => m.status === "pending").length;
+    },
     /** Size of the batch the current (or last) sync started with. */
     syncTotal: 0,
     /** Mutations of that batch that have reached the server so far. */
@@ -209,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 });
@@ -245,12 +317,13 @@ export function createAirplaneClient(options) {
     if (h?.revert) {
       await h.revert({ db, cache: createCacheApi(), variables: row.variables });
       await db.mutations.delete(id);
-      return;
+    } else {
+      const later = (await db.mutations.where("id").above(row.id).toArray()).filter((m) => m.status !== "syncing");
+      if (row.undo) await applyUndo(db, row.undo);
+      await db.mutations.delete(id);
+      for (const m of later) await applyMutation(m, { rebase: true });
     }
-    const later = (await db.mutations.where("createdAt").above(row.createdAt).toArray()).filter((m) => m.status !== "syncing");
-    if (row.undo) await applyUndo(db, row.undo);
-    await db.mutations.delete(id);
-    for (const m of later) await applyMutation(m, { rebase: true });
+    void sync();
   }
   async function retry(id) {
     await db.mutations.update(id, { status: "pending", error: void 0 });
@@ -259,13 +332,32 @@ export function createAirplaneClient(options) {
   let syncPromise = null;
   function sync() {
     if (syncPromise) return syncPromise;
-    syncPromise = runSync().finally(() => syncPromise = null);
+    syncPromise = runSyncLocked().finally(() => syncPromise = null);
     return syncPromise;
   }
+  async function sendable() {
+    const rows = await db.mutations.orderBy("createdAt").toArray();
+    const queue = [];
+    for (const row of rows) {
+      if (row.status === "failed" && stopOnFailure) break;
+      if (row.status === "pending") queue.push(row);
+    }
+    return queue;
+  }
+  const syncLock = `nuxt-airplane:sync:${options.dbName}`;
+  async function runSyncLocked() {
+    const locks = typeof navigator === "object" ? navigator.locks : void 0;
+    if (!locks) return runSync();
+    await locks.request(syncLock, async () => {
+      await ready;
+      await requeueStuck();
+      await runSync();
+    });
+  }
   async function runSync() {
     await ready;
     if (!state.online) return;
-    const queue = await db.mutations.where("status").equals("pending").sortBy("createdAt");
+    const queue = await sendable();
     if (!queue.length) return;
     state.syncing = true;
     state.syncTotal = queue.length;
@@ -277,16 +369,19 @@ 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;
           }
           await db.mutations.update(row.id, { status: "pending" });
@@ -299,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();
@@ -317,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/composables/useSync.d.ts

@@ -13,6 +13,8 @@ export interface UseSyncReturn {
     synced: ComputedRef<boolean>;
     /** Mutations still waiting to reach the server, oldest first. */
     pending: Ref<MutationRow[]>;
+    /** Pending mutations held back because an older one failed (see the `stopOnFailure` option). */
+    blocked: Ref<number>;
     /** Size of the batch the current (or last) sync started with. */
     syncTotal: Ref<number>;
     /** How many of that batch have been sent so far. */

package/dist/runtime/composables/useSync.js

@@ -12,6 +12,7 @@ export function useSync() {
       syncing: computed(() => false),
       synced: computed(() => true),
       pending: computed(() => []),
+      blocked: computed(() => 0),
       syncTotal: computed(() => 0),
       syncCount: computed(() => 0),
       lastError: computed(() => null),
@@ -33,6 +34,7 @@ export function useSync() {
     syncing: toRef(state, "syncing"),
     synced: client.synced,
     pending: toRef(state, "pending"),
+    blocked: toRef(state, "blocked"),
     syncTotal: toRef(state, "syncTotal"),
     syncCount: toRef(state, "syncCount"),
     lastError: toRef(state, "lastError"),

package/dist/runtime/db.d.ts

@@ -6,7 +6,14 @@ export declare const MODULE_STORES: {
 };
 /** Tables that hold module bookkeeping rather than cached data. */
 export declare const BOOKKEEPING_TABLES: Set<string>;
-export declare function createDb(name: string, stores?: Record<string, string>, version?: number): AirplaneDexie;
+export interface CreateDbOptions {
+    /**
+     * Warn (once per table and index) when a boolean is written to an indexed
+     * key path, since IndexedDB cannot index booleans. Defaults to dev mode.
+     */
+    warnOnBooleanIndex?: boolean;
+}
+export declare function createDb(name: string, stores?: Record<string, string>, version?: number, { warnOnBooleanIndex }?: CreateDbOptions): AirplaneDexie;
 /**
  * Runs `fn` in a read-write transaction over every table and returns the
  * writes it made. If `fn` throws, the transaction aborts and nothing is kept.

package/dist/runtime/db.js

@@ -5,12 +5,33 @@ export const MODULE_STORES = {
   meta: "&key"
 };
 export const BOOKKEEPING_TABLES = /* @__PURE__ */ new Set(["mutations", "meta"]);
-export function createDb(name, stores = {}, version = 1) {
+export function createDb(name, stores = {}, version = 1, { warnOnBooleanIndex = import.meta.dev } = {}) {
   const db = new Dexie(name);
   db.version(version).stores({ ...MODULE_STORES, ...stores });
-  installUndoLog(db);
+  installUndoLog(db, warnOnBooleanIndex);
   return db;
 }
+function valueAt(row, keyPath) {
+  return keyPath.split(".").reduce((o, k) => o && typeof o === "object" ? o[k] : void 0, row);
+}
+function warnBooleanIndexes(table, values, warned) {
+  const { primaryKey, indexes } = table.schema;
+  for (const index of [primaryKey, ...indexes]) {
+    if (!index.keyPath || index.name?.includes("(virtual-from:")) continue;
+    const label = index.name ?? "primary key";
+    const id = `${table.name}/${label}`;
+    if (warned.has(id)) continue;
+    const paths = Array.isArray(index.keyPath) ? index.keyPath : [index.keyPath];
+    for (const value of values) {
+      const at = paths.findIndex((path) => typeof valueAt(value, path) === "boolean");
+      if (at === -1) continue;
+      warned.add(id);
+      const where = paths.length > 1 ? `index "${label}" at "${paths[at]}"` : `index "${label}"`;
+      console.warn(`[nuxt-airplane] Table "${table.name}": ${where} received a boolean, and IndexedDB cannot index booleans; store it as 0 | 1 (see the docs on stores).`);
+      break;
+    }
+  }
+}
 const logs = /* @__PURE__ */ new WeakMap();
 function keysOf(index, values) {
   return index.extractKey ? values.map((v) => index.extractKey(v)) : void 0;
@@ -36,7 +57,8 @@ async function recordBefore(table, req) {
   const before = await table.getMany({ trans, keys });
   return { entries: keys.map((key, i) => ({ table: name, key, before: before[i] })) };
 }
-function installUndoLog(db) {
+function installUndoLog(db, warnOnBooleanIndex = false) {
+  const warned = /* @__PURE__ */ new Set();
   db.use({
     stack: "dbcore",
     name: "nuxt-airplane-undo",
@@ -48,6 +70,7 @@ function installUndoLog(db) {
         return {
           ...table,
           async mutate(req) {
+            if (warnOnBooleanIndex && (req.type === "add" || req.type === "put")) warnBooleanIndexes(table, req.values, warned);
             const log = logs.get(req.trans);
             if (!log) return table.mutate(req);
             const { entries, afterMutate } = await recordBefore(table, req);

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

@@ -170,7 +170,9 @@ declare const _default: import("#app").Plugin<{
                     })[];
                     before?: unknown;
                 }[] | undefined;
+                tempIds?: string[] | undefined;
             }[];
+            readonly blocked: number;
             syncTotal: number;
             syncCount: number;
             lastError: string | null;
@@ -195,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>;
@@ -376,7 +379,9 @@ declare const _default: import("#app").Plugin<{
                     })[];
                     before?: unknown;
                 }[] | undefined;
+                tempIds?: string[] | undefined;
             }[];
+            readonly blocked: number;
             syncTotal: number;
             syncCount: number;
             lastError: string | null;
@@ -401,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/plugin.client.js

@@ -14,7 +14,7 @@ function collect(exports) {
     if (item === void 0) continue;
     const kind = item && typeof item === "object" ? item[HANDLER_KIND] : void 0;
     if (!kind) {
-      if (import.meta.dev) console.warn("[nuxt-airplane] Ignoring a default export in the handlers directory that was not created with defineMutationHandler(s), defineQueryHandler(s) or defineAirplaneStores.");
+      console.warn("[nuxt-airplane] Ignoring a default export in the handlers directory that was not created with a define* helper (defineMutationHandler(s), defineQueryHandler(s), defineAirplaneStores, defineAirplaneRequest).");
       continue;
     }
     if (kind === "queries") Object.assign(queryHandlers, item);

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.
@@ -213,4 +244,6 @@ export interface AirplaneRuntimeConfig {
     headers?: Record<string, string>;
     /** Deploy-specific part of the cache key; see the `cacheKey` module option. */
     cacheKey?: string;
+    /** A failed mutation holds back the ones queued after it; see the `stopOnFailure` module option. Default `true`. */
+    stopOnFailure?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treygrr/nuxt-airplane",
-  "version": "0.1.1",
+  "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",