@treygrr/nuxt-airplane 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 treygrr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="./docs/public/logo.png" width="140" height="140" alt="nuxt-airplane logo">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# nuxt-airplane
+
+[![npm version](https://img.shields.io/npm/v/%40treygrr%2Fnuxt-airplane?color=00DC82&labelColor=020420)](https://www.npmjs.com/package/@treygrr/nuxt-airplane)
+[![License](https://img.shields.io/npm/l/%40treygrr%2Fnuxt-airplane?color=00DC82&labelColor=020420)](./LICENSE)
+[![Nuxt](https://img.shields.io/badge/Nuxt-4-00DC82?logo=nuxt&labelColor=020420)](https://nuxt.com)
+
+Airplane mode for your GraphQL app.
+
+📖 **[Documentation](https://treygrr.github.io/nuxt-airplane/)**
+
+Give it an endpoint and your `.gql` files. Every operation becomes a typed
+`useQuery` or `useMutation`, results live in IndexedDB (via Dexie), and anything
+you change mid-flight queues up and lands on the server once you're back on the
+ground.
+
+## Setup
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@treygrr/nuxt-airplane'],
+  airplane: {
+    endpoint: 'https://api.example.com/graphql',
+  },
+})
+```
+
+| Option | Default | |
+| --- | --- | --- |
+| `endpoint` | `/api/graphql` | GraphQL endpoint. A relative path is resolved against the app itself. |
+| `schema` | – | SDL file or URL. When omitted the endpoint is introspected. In dev a relative endpoint is introspected once the dev server is up; the last good schema is cached in `node_modules/.cache/nuxt-airplane`. |
+| `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. |
+| `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. |
+
+## Operations
+
+Every named operation in your documents becomes available by name. Fragments are
+resolved across files.
+
+```graphql
+# app/graphql/sites.gql
+query GetSites { sites { id name archived } }
+mutation RenameSite($id: ID!, $name: String!) { renameSite(id: $id, name: $name) { id name } }
+```
+
+```vue
+<script setup lang="ts">
+const { data, loading, fetching, error, refresh } = useQuery('GetSites')
+const rename = useMutation('RenameSite')
+
+await rename.mutate({ id: 'site-1', name: 'New name' })
+</script>
+```
+
+Both are fully typed from the schema: the document name is checked, variables
+and `data` get the generated operation types.
+
+`useQuery` returns **live data from the local cache**, not the network response.
+A cached result renders immediately and a refetch runs in the background when
+online; any mutation handler that touches the cache updates `data` right away.
+
+`useMutation().mutate()` resolves as soon as the change is applied locally and
+queued. Sending it to the server happens in the sync loop.
+
+## Mutation handlers
+
+Handlers describe how a queued mutation shows up in the local cache. Put files
+under `app/airplane/` and they are picked up automatically.
+
+```ts
+// app/airplane/sites.ts
+export default defineMutationHandlers({
+  RenameSite: {
+    // Runs when the mutation is queued, so the UI reflects it immediately.
+    apply: ({ cache, variables }) =>
+      cache.update('GetSites', (data) => {
+        const site = data.sites.find(s => s.id === variables.id)
+        if (site) site.name = variables.name
+      }),
+    // Optional: summary for the pending list, computed before `apply`.
+    describe: ({ variables }) => `Rename site to ${variables.name}`,
+    // Optional: merge the server's response once it has been sent.
+    reconcile: ({ cache, variables }, result) => { /* ... */ },
+    // Optional: undo `apply`. When omitted, the rows `apply` touched are
+    // snapshotted and restored on rollback.
+    revert: ({ cache, variables }) => { /* ... */ },
+    // Queries to refetch after the server accepted it. Defaults to every active query.
+    refetch: ['GetSites'],
+  },
+})
+```
+
+The handler context gives you:
+
+- `cache.update(name, updater)` / `cache.update(name, variables, updater)`: edit cached responses in place or return a replacement.
+- `cache.get(name, variables?)`, `cache.set(name, variables, data)`, `cache.invalidate(name)`.
+- `db`: the Dexie instance (`queries` and `mutations` tables) if you need to go lower.
+- `variables`: the mutation's input, typed.
+
+## Auth and headers
+
+```ts
+// app/airplane/request.ts
+export default defineAirplaneRequest({
+  headers: () => ({ Authorization: `Bearer ${useCookie('token').value}` }), // runs per request, composables work
+  credentials: 'include',
+  onResponse: res => { if (res.status === 401) navigateTo('/login') },
+})
+```
+
+Headers are computed when a request is sent, so a mutation queued offline goes out later with the token valid at that moment. Static headers go in the `headers` module option; `schemaHeaders` covers build-time introspection of a protected endpoint.
+
+## Your own tables
+
+Opt a query into normalized storage: declare Dexie tables with `defineAirplaneStores`, then tell the module how to `store` a response and `read` it back with `defineQueryHandlers`. Mutation handlers write to the tables directly and every query reading them updates on its own. Rollback still works: writes made during `apply` are recorded by an undo log.
+
+```ts
+// app/airplane/stores.ts
+declare global { interface NuxtAirplaneStores { sites: { id: string, name: string, archived: boolean } } }
+export default defineAirplaneStores({ sites: '&id, name, archived' })
+
+// app/airplane/queries.ts
+export default defineQueryHandlers({
+  GetSites: {
+    store: ({ db }, data) => db.sites.bulkPut(data.sites),
+    read: async ({ db }) => ({ sites: await db.sites.toArray() }),
+  },
+})
+
+// app/airplane/sites.ts
+export default defineMutationHandlers({
+  RenameSite: { apply: ({ db, variables }) => db.sites.update(variables.id, { name: variables.name }) },
+})
+```
+
+One file per operation also works: `defineMutationHandler('RenameSite', { … })` and `defineQueryHandler('GetSites', { … })` declare a single operation, and a folder with an `index.ts` is imported through its index only, so you can compose there.
+
+Paginated queries can opt into fetching every page in the background so the whole set is available offline: `prefetch: { next: (data, vars) => data.pageInfo.hasNextPage ? { ...vars, after: data.pageInfo.endCursor } : null, when: () => settings.cacheCatalog }`. `useSync().prefetching` counts the runs in progress.
+
+## Sync state
+
+```ts
+const { online, syncing, synced, pending, syncTotal, syncCount, lastError, sync, rollback, retry, goOffline, goOnline } = useSync()
+```
+
+- `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 network failure stops the batch and keeps everything queued; the next `online` event (or `sync()`) resumes it.
+- `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
+
+Cached data and the outbox live unencrypted in IndexedDB under your origin: clear them on sign-out with `useAirplane().clear()`, don't queue mutations whose variables you wouldn't store (change-password, card numbers), and render server error messages as text. Credentials are never persisted; `schemaHeaders` never ships. Full notes in the [Security guide](https://treygrr.github.io/nuxt-airplane/guide/security).
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and the [pull request guidelines](https://treygrr.github.io/nuxt-airplane/contributing/pull-requests).
+
+## Development
+
+```sh
+npm install
+npm run dev          # playground with an in-memory Apollo server at /api/graphql
+npm run lint
+npm run test
+npm run test:types
+```
+
+The playground (`playground/`) has a sites/items inventory demo: toggle the
+network in devtools, make changes, roll some back, and go online again.

package/dist/module.d.mts

@@ -0,0 +1,34 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /** URL of the GraphQL endpoint. A path like `/api/graphql` is resolved against the app's own origin. */
+    endpoint: string;
+    /**
+     * Where the schema comes from: an SDL file or a URL. When omitted the
+     * endpoint is introspected (in dev, once the server is listening).
+     */
+    schema?: string;
+    /** Globs, relative to `srcDir`, of the `.gql` / `.graphql` files holding the operations. */
+    documents: string[];
+    /** Directory, relative to `srcDir`, scanned for `defineMutationHandlers` / `defineQueryHandlers` / `defineAirplaneStores` files. */
+    handlersDir: string;
+    /** Static headers sent with every request, e.g. an API key. Public: they ship to the browser. */
+    headers?: Record<string, string>;
+    /** Headers for build-time introspection of a protected endpoint, e.g. from `process.env`. Never shipped. */
+    schemaHeaders?: Record<string, string>;
+    /** Name of the IndexedDB database. */
+    dbName: string;
+    /**
+     * Changes to this value wipe the local cache on the next load (the outbox is
+     * kept). Set it per deploy, e.g. a git SHA or build id. A hash of the GraphQL
+     * documents is always mixed in, so editing a query busts the cache on its own.
+     * Overridable at runtime with `NUXT_PUBLIC_AIRPLANE_CACHE_KEY`.
+     */
+    cacheKey?: string;
+    /** Extra options passed to the `typescript` / `typescript-operations` codegen plugins. */
+    codegen: Record<string, unknown>;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-airplane",
+  "configKey": "airplane",
+  "compatibility": {
+    "nuxt": ">=4.0.0"
+  },
+  "version": "0.1.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,271 @@
+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';
+import { buildSchema, printSchema, parse, Kind, print, getIntrospectionQuery, buildClientSchema, visit } from 'graphql';
+
+function isUrl(value) {
+  return /^https?:\/\//.test(value);
+}
+async function introspect(url, headers = {}, attempts = 10) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body: JSON.stringify({ query: getIntrospectionQuery() }),
+    signal: AbortSignal.timeout(15e3)
+  });
+  if (res.status === 503 && attempts > 1) {
+    await new Promise((r) => setTimeout(r, 1e3));
+    return introspect(url, headers, attempts - 1);
+  }
+  if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+  const body = await res.json();
+  if (body.errors?.length) throw new Error(body.errors.map((e) => e.message).join(", "));
+  return buildClientSchema(body.data);
+}
+async function loadSchema(source, log) {
+  const cacheFile = join(source.cacheDir, "schema.graphql");
+  let schema = null;
+  try {
+    if (source.schema && !isUrl(source.schema)) {
+      schema = buildSchema(await readFile(source.schema, "utf8"));
+    } else {
+      const url = source.schema ?? source.endpoint;
+      if (isUrl(url)) schema = await introspect(url, source.headers);
+    }
+  } catch (error) {
+    log.warn(`Could not load GraphQL schema: ${error.message}`);
+  }
+  if (schema) {
+    await mkdir(dirname(cacheFile), { recursive: true });
+    await writeFile(cacheFile, printSchema(schema));
+  } else if (existsSync(cacheFile)) {
+    schema = buildSchema(await readFile(cacheFile, "utf8"));
+  }
+  return schema;
+}
+function fragmentSpreads(node) {
+  const names = /* @__PURE__ */ new Set();
+  visit(node, { FragmentSpread: (s) => void names.add(s.name.value) });
+  return names;
+}
+async function loadDocuments(patterns, cwd, log) {
+  const files = (await glob(patterns, { cwd, absolute: true, ignore: ["**/node_modules/**"] })).sort();
+  const fragments = /* @__PURE__ */ new Map();
+  const ops = [];
+  for (const file of files) {
+    let doc;
+    try {
+      doc = parse(await readFile(file, "utf8"));
+    } catch (error) {
+      log.warn(`Skipping ${file}: ${error.message}`);
+      continue;
+    }
+    for (const def of doc.definitions) {
+      if (def.kind === Kind.FRAGMENT_DEFINITION) fragments.set(def.name.value, def);
+      else if (def.kind === Kind.OPERATION_DEFINITION) {
+        if (!def.name) log.warn(`Skipping anonymous ${def.operation} in ${file}: operations must be named`);
+        else ops.push({ node: def, file });
+      }
+    }
+  }
+  const operations = {};
+  const documentNodes = [];
+  for (const { node, file } of ops) {
+    const name = node.name.value;
+    if (operations[name]) {
+      log.warn(`Duplicate operation "${name}" in ${file}, keeping the first one`);
+      continue;
+    }
+    const needed = /* @__PURE__ */ new Map();
+    const queue = [...fragmentSpreads(node)];
+    while (queue.length) {
+      const spread = queue.shift();
+      if (needed.has(spread)) continue;
+      const fragment = fragments.get(spread);
+      if (!fragment) {
+        log.warn(`Operation "${name}" spreads unknown fragment "${spread}"`);
+        continue;
+      }
+      needed.set(spread, fragment);
+      queue.push(...fragmentSpreads(fragment));
+    }
+    const documentNode = { kind: Kind.DOCUMENT, definitions: [node, ...needed.values()] };
+    documentNodes.push(documentNode);
+    operations[name] = { name, kind: node.operation, source: print(documentNode) };
+  }
+  return { operations, documentNodes, files };
+}
+function operationMap(ops, kind, suffix) {
+  return ops.filter((op) => op.kind === kind).map((op) => `    ${JSON.stringify(op.name)}: { result: ${op.name}${suffix}, variables: ${op.name}${suffix}Variables }`).join("\n");
+}
+const virtualModules = `
+declare module '#nuxt-airplane/documents' {
+  export const documents: Record<string, { name: string, kind: 'query' | 'mutation' | 'subscription', source: string }>
+  export const documentsHash: string
+}
+declare module '#nuxt-airplane/handlers' {
+  export const handlers: unknown[]
+}
+`;
+async function generateTypes(schema, docs, config = {}) {
+  const ops = Object.values(docs.operations);
+  if (!schema) {
+    return [
+      "// Generated by nuxt-airplane. No GraphQL schema could be loaded, so operations are untyped.",
+      "export {}",
+      "declare global {",
+      "  interface NuxtAirplaneQueries { [name: string]: { result: any, variables: any } }",
+      "  interface NuxtAirplaneMutations { [name: string]: { result: any, variables: any } }",
+      "}",
+      virtualModules
+    ].join("\n");
+  }
+  const generated = await codegen({
+    filename: "nuxt-airplane.ts",
+    schema: parse(printSchema(schema)),
+    documents: docs.documentNodes.map((document) => ({ document })),
+    config: {
+      namingConvention: "keep",
+      // `ID` comes back as a string over the wire; typing it as such keeps variables simple.
+      scalars: { ID: { input: "string", output: "string" } },
+      ...config
+    },
+    plugins: [{ typescript: {} }, { typescriptOperations: {} }],
+    pluginMap: { typescript: typescriptPlugin, typescriptOperations: typescriptOperationsPlugin }
+  });
+  return [
+    "// Generated by nuxt-airplane from your GraphQL documents. Do not edit.",
+    generated,
+    "declare global {",
+    "  interface NuxtAirplaneQueries {",
+    operationMap(ops, "query", "Query"),
+    "  }",
+    "  interface NuxtAirplaneMutations {",
+    operationMap(ops, "mutation", "Mutation"),
+    "  }",
+    "}",
+    virtualModules
+  ].join("\n");
+}
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-airplane",
+    configKey: "airplane",
+    compatibility: { nuxt: ">=4.0.0" }
+  },
+  defaults: {
+    endpoint: "/api/graphql",
+    documents: ["**/*.gql", "**/*.graphql"],
+    handlersDir: "airplane",
+    dbName: "nuxt-airplane",
+    codegen: {}
+  },
+  async setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const logger = useLogger("nuxt-airplane");
+    const { srcDir } = nuxt.options;
+    const cacheDir = join(nuxt.options.rootDir, "node_modules/.cache/nuxt-airplane");
+    nuxt.options.runtimeConfig.public.airplane = {
+      endpoint: options.endpoint,
+      dbName: options.dbName,
+      cacheKey: options.cacheKey ?? "",
+      headers: options.headers ?? {}
+    };
+    nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
+    nuxt.options.vite.optimizeDeps ||= {};
+    nuxt.options.vite.optimizeDeps.include ||= [];
+    nuxt.options.vite.optimizeDeps.include.push("dexie", "ohash");
+    let introspectionUrl = /^https?:\/\//.test(options.endpoint) ? options.endpoint : void 0;
+    let docs = { operations: {}, documentNodes: [], files: [] };
+    async function reloadDocuments() {
+      docs = await loadDocuments(options.documents, srcDir, logger);
+      return docs;
+    }
+    async function handlerFiles() {
+      const dir = join(srcDir, options.handlersDir);
+      const files = (await glob(["**/*.{ts,js,mts,mjs}"], { cwd: dir, absolute: true })).sort();
+      const isIndex = (file) => /^index\.[mc]?[tj]s$/.test(basename(file));
+      const indexDirs = files.filter(isIndex).map((file) => dirname(file));
+      return files.filter((file) => {
+        const owner = indexDirs.find((d) => file.startsWith(d + sep));
+        return !owner || dirname(file) === owner && isIndex(file);
+      });
+    }
+    await reloadDocuments();
+    nuxt.options.watch.push(...docs.files);
+    const documentsTemplate = addTemplate({
+      filename: "nuxt-airplane/documents.mjs",
+      write: true,
+      getContents: () => [
+        `export const documents = ${JSON.stringify(docs.operations, null, 2)}`,
+        // Part of the cache key: any change to an operation invalidates cached responses.
+        `export const documentsHash = ${JSON.stringify(hash(Object.values(docs.operations).map((op) => op.source)))}`,
+        ""
+      ].join("\n")
+    });
+    const handlersTemplate = addTemplate({
+      filename: "nuxt-airplane/handlers.mjs",
+      write: true,
+      getContents: async () => {
+        const files = await handlerFiles();
+        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")}
+export const handlers = [${list}]
+`;
+      }
+    });
+    nuxt.options.alias["#nuxt-airplane"] = resolver.resolve("./runtime/types");
+    nuxt.options.alias["#nuxt-airplane/documents"] = documentsTemplate.dst;
+    nuxt.options.alias["#nuxt-airplane/handlers"] = handlersTemplate.dst;
+    addTypeTemplate({
+      filename: "types/nuxt-airplane.d.ts",
+      getContents: async () => {
+        const schemaSource = options.schema && !/^https?:\/\//.test(options.schema) ? resolve(nuxt.options.rootDir, options.schema) : options.schema;
+        const schema = await loadSchema({ schema: schemaSource, endpoint: introspectionUrl ?? "", cacheDir, headers: options.schemaHeaders }, logger);
+        if (!schema) logger.warn("No GraphQL schema available yet, operations are untyped");
+        return generateTypes(schema, docs, options.codegen);
+      }
+    });
+    async function regenerate() {
+      await reloadDocuments();
+      await updateTemplates({ filter: (t) => t.filename.includes("nuxt-airplane") });
+    }
+    if (nuxt.options.dev) {
+      let introspectDevServer = function() {
+        if (introspectionUrl || options.schema || !devUrl || !nitroBuilt) return;
+        introspectionUrl = new URL(options.endpoint, devUrl).href;
+        regenerate().catch((error) => logger.error("Failed to generate GraphQL types", error));
+      };
+      let devUrl;
+      let nitroBuilt = false;
+      nuxt.hook("listen", (_server, listener) => {
+        devUrl = listener.url;
+        introspectDevServer();
+      });
+      nuxt.hook("nitro:init", (nitro) => {
+        nitro.hooks.hook("dev:reload", () => {
+          nitroBuilt = true;
+          introspectDevServer();
+        });
+      });
+      nuxt.hook("builder:watch", async (_event, path) => {
+        const abs = join(srcDir, path);
+        const isDocument = /\.(?:gql|graphql)$/.test(abs);
+        const isHandler = abs.startsWith(join(srcDir, options.handlersDir));
+        if (isDocument || isHandler) await regenerate();
+      });
+    }
+    addImportsDir(resolver.resolve("./runtime/composables"));
+    addPlugin({ src: resolver.resolve("./runtime/plugin.client"), mode: "client" });
+  }
+});
+
+export { module$1 as default };