@treygrr/nuxt-airplane 0.0.0-stage → 0.1.2

package/dist/runtime/types.d.ts

@@ -0,0 +1,218 @@
+import type { Dexie, EntityTable, IndexableType, Table } from 'dexie';
+declare global {
+    /**
+     * Augmented by the generated `types/nuxt-airplane.d.ts` with one entry per
+     * query document found in the user's `.gql` / `.graphql` files.
+     */
+    interface NuxtAirplaneQueries {
+    }
+    /** Same as {@link NuxtAirplaneQueries}, for mutation documents. */
+    interface NuxtAirplaneMutations {
+    }
+    /**
+     * Row types of the tables declared with `defineAirplaneStores`. Augment it
+     * yourself so `db.<table>` is typed inside handlers:
+     *
+     * ```ts
+     * declare global {
+     *   interface NuxtAirplaneStores { sites: { id: string, name: string } }
+     * }
+     * ```
+     */
+    interface NuxtAirplaneStores {
+    }
+}
+export type QueryName = keyof NuxtAirplaneQueries & string;
+export type MutationName = keyof NuxtAirplaneMutations & string;
+export type QueryResult<N extends QueryName> = NuxtAirplaneQueries[N] extends {
+    result: infer R;
+} ? R : never;
+export type QueryVariables<N extends QueryName> = NuxtAirplaneQueries[N] extends {
+    variables: infer V;
+} ? V : never;
+export type MutationResult<N extends MutationName> = NuxtAirplaneMutations[N] extends {
+    result: infer R;
+} ? R : never;
+export type MutationVariables<N extends MutationName> = NuxtAirplaneMutations[N] extends {
+    variables: infer V;
+} ? V : never;
+export interface OperationDocument {
+    name: string;
+    kind: 'query' | 'mutation' | 'subscription';
+    source: string;
+}
+/**
+ * A cached query response, keyed by document name + variables. For queries
+ * with a `read` handler only the metadata is kept and `data` is `null`.
+ */
+export interface QueryRow {
+    key: string;
+    document: string;
+    variables: unknown;
+    data: unknown;
+    updatedAt: number;
+}
+export type MutationStatus = 'pending' | 'syncing' | 'failed';
+/** One write recorded while `apply` ran, with the row as it was before. */
+export interface UndoEntry {
+    table: string;
+    key: IndexableType;
+    /** `undefined` when the row did not exist, in which case undo deletes it. */
+    before?: unknown;
+}
+/** A queued mutation waiting to reach the server. */
+export interface MutationRow {
+    id: number;
+    document: string;
+    variables: unknown;
+    status: MutationStatus;
+    createdAt: number;
+    /** Human-readable summary from the handler's `describe`, or the humanized document name. */
+    description: string;
+    error?: string;
+    /** Writes made by `apply`, oldest first, used to roll the mutation back. */
+    undo?: UndoEntry[];
+}
+/** Module bookkeeping, e.g. the cache key the data was written under. */
+export interface MetaRow {
+    key: string;
+    value: string;
+}
+export type AirplaneDexie = Dexie & {
+    queries: EntityTable<QueryRow, 'key'>;
+    mutations: EntityTable<MutationRow, 'id'>;
+    meta: EntityTable<MetaRow, 'key'>;
+} & {
+    [K in keyof NuxtAirplaneStores]: Table<NuxtAirplaneStores[K], IndexableType>;
+};
+/** Mutate `data` in place, or return a replacement. */
+export type Updater<T> = (data: T, variables: unknown) => T | undefined | void;
+/** Read and write the cached query responses from inside a mutation handler. */
+export interface CacheApi {
+    /** Update every cached response of a query document. */
+    update<N extends QueryName>(name: N, updater: Updater<QueryResult<N>>): Promise<void>;
+    /** Update the cached response for one exact set of variables. */
+    update<N extends QueryName>(name: N, variables: QueryVariables<N>, updater: Updater<QueryResult<N>>): Promise<void>;
+    get<N extends QueryName>(name: N, variables?: QueryVariables<N>): Promise<QueryResult<N> | undefined>;
+    set<N extends QueryName>(name: N, variables: QueryVariables<N>, data: QueryResult<N>): Promise<void>;
+    /** Drop the cached responses of a query document and refetch it once `apply` is done. */
+    invalidate(name: QueryName): Promise<void>;
+}
+export interface HandlerContext<V = unknown> {
+    db: AirplaneDexie;
+    cache: CacheApi;
+    variables: V;
+}
+export interface MutationHandler<N extends MutationName = MutationName> {
+    /**
+     * A human-readable summary for the pending list, e.g. "Archive North Warehouse".
+     * Computed once when the mutation is queued, before `apply`, so it can read
+     * the data as it was. Defaults to the humanized document name.
+     */
+    describe?: string | ((ctx: HandlerContext<MutationVariables<N>>) => string | Promise<string>);
+    /**
+     * 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;
+    /**
+     * Runs when a queued mutation is rolled back. When omitted the writes made
+     * by `apply` are undone from the recorded log instead.
+     */
+    revert?: (ctx: HandlerContext<MutationVariables<N>>) => unknown;
+    /** Queries to refetch after the mutation has been sent. Defaults to every active query. */
+    refetch?: QueryName[];
+}
+export type MutationHandlers = {
+    [N in MutationName]?: MutationHandler<N>;
+};
+export interface QueryHandlerContext<V = unknown> {
+    db: AirplaneDexie;
+    variables: V;
+}
+/**
+ * Walk a paginated query to the end after any page of it is fetched, so the
+ * whole set is available offline.
+ */
+export interface QueryPrefetch<N extends QueryName = QueryName> {
+    /** Variables of the page after `data`, or `null` / `undefined` when there is none. */
+    next: (data: QueryResult<N>, variables: QueryVariables<N>) => QueryVariables<N> | null | undefined;
+    /** Safety cap on pages fetched per run. Default 1000. */
+    maxPages?: number;
+    /** Skip the run when this returns `false`: metered connection, feature flag, user setting… */
+    when?: () => boolean;
+}
+export interface QueryHandler<N extends QueryName = QueryName> {
+    /** Fetch every following page in the background once a page of this query is fetched. */
+    prefetch?: QueryPrefetch<N>;
+    /** Writes a fresh response into your own tables. Runs inside a Dexie transaction. */
+    store?: (ctx: QueryHandlerContext<QueryVariables<N>>, data: QueryResult<N>) => unknown;
+    /**
+     * Builds the query's result from your tables. Runs inside Dexie's
+     * `liveQuery`, so whatever it reads is observed and `data` stays live.
+     */
+    read?: (ctx: QueryHandlerContext<QueryVariables<N>>) => QueryResult<N> | null | undefined | Promise<QueryResult<N> | null | undefined>;
+}
+export type QueryHandlers = {
+    [N in QueryName]?: QueryHandler<N>;
+};
+/** Extra Dexie tables, in Dexie's `stores()` syntax. */
+export interface AirplaneStores {
+    stores: Record<string, string>;
+    /** Schema version. Bump it when changing indexes of existing tables. */
+    version?: number;
+}
+/** What is being sent, for `headers` / `onResponse` to decide on. */
+export interface AirplaneRequestContext {
+    document: string;
+    kind: OperationDocument['kind'];
+    variables: unknown;
+}
+/** How requests to the GraphQL endpoint are made; see `defineAirplaneRequest`. */
+export interface AirplaneRequestOptions {
+    /**
+     * Extra headers, or a function returning them. The function runs for every
+     * request, inside the Nuxt app context, so it can read a cookie or state and
+     * always sends the current token, also for mutations synced later.
+     */
+    headers?: HeadersInit | ((ctx: AirplaneRequestContext) => HeadersInit | undefined | Promise<HeadersInit | undefined>);
+    /** `fetch` credentials mode, e.g. `'include'` for cookie auth across origins. */
+    credentials?: RequestCredentials;
+    /** A fetch implementation to use instead of the global one. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Abort a request after this many milliseconds (default 30 000). A request
+     * that never settles would otherwise hold the sync loop for the session.
+     */
+    timeout?: number;
+    /** Sees every response before it is parsed, e.g. to react to a 401. */
+    onResponse?: (response: Response, ctx: AirplaneRequestContext) => unknown;
+}
+/** Marks what a file under the handlers directory default-exports. */
+export declare const HANDLER_KIND: unique symbol;
+export type HandlerKind = 'mutations' | 'queries' | 'stores' | 'request';
+export interface GraphQLError {
+    message: string;
+    path?: (string | number)[];
+    extensions?: Record<string, unknown>;
+}
+export interface GraphQLResponse<T = unknown> {
+    data?: T | null;
+    errors?: GraphQLError[];
+}
+export declare class GraphQLRequestError extends Error {
+    errors: GraphQLError[];
+    constructor(errors: GraphQLError[]);
+}
+export interface AirplaneRuntimeConfig {
+    endpoint: string;
+    dbName: string;
+    /** Static headers from the `headers` module option. */
+    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/dist/runtime/types.js

@@ -0,0 +1,8 @@
+export const HANDLER_KIND = Symbol.for("nuxt-airplane:kind");
+export class GraphQLRequestError extends Error {
+  constructor(errors) {
+    super(errors.map((e) => e.message).join("\n"));
+    this.errors = errors;
+    this.name = "GraphQLRequestError";
+  }
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,98 @@
 {
   "name": "@treygrr/nuxt-airplane",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+    "nuxt-module",
+    "graphql",
+    "offline",
+    "offline-first",
+    "dexie",
+    "indexeddb",
+    "sync"
+  ],
+  "repository": "treygrr/nuxt-airplane",
+  "homepage": "https://github.com/treygrr/nuxt-airplane#readme",
+  "bugs": "https://github.com/treygrr/nuxt-airplane/issues",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "playground",
+    "docs"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
+    "docs:dev": "nuxt dev docs",
+    "docs:build": "nuxt build docs"
+  },
+  "dependencies": {
+    "@graphql-codegen/core": "^6.2.2",
+    "@graphql-codegen/typescript": "^6.1.2",
+    "@graphql-codegen/typescript-operations": "^6.2.0",
+    "@nuxt/kit": "^4.6.3",
+    "dexie": "^4.4.7",
+    "ohash": "^2.0.12",
+    "tinyglobby": "^0.2.17"
+  },
+  "peerDependencies": {
+    "graphql": "^16.8.0 || ^17.0.0"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.4.2",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.6.3",
+    "@nuxt/test-utils": "^4.3.3",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^10.12.0",
+    "fake-indexeddb": "^6.2.7",
+    "graphql": "^17.0.2",
+    "nuxt": "^4.6.3",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.3",
+    "vue-tsc": "^3.3.12"
+  },
+  "overrides": {
+    "minimatch": "^11.0.1",
+    "eslint-plugin-import-x": {
+      "minimatch": "^10.2.6"
+    },
+    "glob": "^14.0.2",
+    "@nuxt/content": {
+      "zod": "^4.6.7"
+    }
+  }
+}