@treygrr/nuxt-airplane 0.1.1 → 0.1.2

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.1.2",
   "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

@@ -193,6 +193,7 @@ export declare function createAirplaneClient(options: AirplaneClientOptions): {
                 before?: unknown;
             }[] | undefined;
         }[];
+        readonly blocked: number;
         syncTotal: number;
         syncCount: number;
         lastError: string | null;

package/dist/runtime/client.js

@@ -16,6 +16,7 @@ export function queryKey(name, variables) {
 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 +37,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 +54,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. */
@@ -245,12 +255,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 +270,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;
@@ -287,6 +317,7 @@ export function createAirplaneClient(options) {
         } catch (error) {
           if (error instanceof GraphQLRequestError) {
             await db.mutations.update(row.id, { status: "failed", error: error.message });
+            if (stopOnFailure) break;
             continue;
           }
           await db.mutations.update(row.id, { status: "pending" });

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

@@ -171,6 +171,7 @@ declare const _default: import("#app").Plugin<{
                     before?: unknown;
                 }[] | undefined;
             }[];
+            readonly blocked: number;
             syncTotal: number;
             syncCount: number;
             lastError: string | null;
@@ -377,6 +378,7 @@ declare const _default: import("#app").Plugin<{
                     before?: unknown;
                 }[] | undefined;
             }[];
+            readonly blocked: number;
             syncTotal: number;
             syncCount: number;
             lastError: string | null;

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

@@ -213,4 +213,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.1.2",
   "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",