@lenne.tech/nuxt-extensions 1.20.1 → 1.22.0

package/dist/runtime/types/sync.d.ts

@@ -0,0 +1,127 @@
+import type { Ref } from 'vue';
+/** The id format a sync model declares (§3). One per model, never mixed. */
+export type LtSyncIdFormat = 'objectId' | 'uuidv7';
+/**
+ * A record as the device holds it. `version` 0 means "created here, not on the server yet";
+ * a tombstone has `deletedAt` set and no `data`.
+ */
+export interface LtSyncRecord<T = Record<string, unknown>> {
+    data?: T;
+    deletedAt: null | string;
+    id: string;
+    updatedAt: null | string;
+    version: number;
+}
+/** Status of one pushed change (§7) */
+export type LtSyncItemStatus = 'applied' | 'conflict' | 'merged' | 'not_found' | 'rejected' | 'retry';
+/** One result of a push, in the order the changes were sent (§6.6) */
+export interface LtSyncPushResult {
+    /** Reason of a `rejected` change, e.g. `VALIDATION_FAILED`, `FORBIDDEN`, `ID_UNAVAILABLE` */
+    code?: string;
+    details?: unknown;
+    id: string;
+    mutationId: string;
+    /** The server's record on `conflict` and `merged` (a tombstone when it was deleted) */
+    record?: {
+        data?: Record<string, unknown>;
+        deletedAt?: null | string;
+        id: string;
+        updatedAt?: null | string;
+        version: number;
+    };
+    status: LtSyncItemStatus;
+    version?: number;
+}
+/** What `onConflict` receives when the server did not apply a local change */
+export interface LtSyncConflict<T = Record<string, unknown>> {
+    /** The local change the server refused */
+    change: {
+        data?: Partial<T>;
+        op: 'delete' | 'upsert';
+    };
+    /** The local record as it was before the conflict was resolved */
+    local: LtSyncRecord<T> | undefined;
+    /** The server's current record; a tombstone (`deletedAt` set) when it was deleted there */
+    server: LtSyncRecord<T>;
+}
+/**
+ * The answer of `onConflict`: keep the server's state (`'server'`), or send `data` again on top
+ * of it. A record the server deleted stays deleted: an upsert on a tombstone is a conflict again (§6.3).
+ */
+export type LtSyncConflictResolution<T = Record<string, unknown>> = 'server' | {
+    data: Partial<T>;
+};
+/** Outcome of one sync run */
+export interface LtSyncResult {
+    applied: number;
+    /** Conflicts of this run, after `onConflict` (or the server-wins default) resolved them */
+    conflicts: LtSyncPushResult[];
+    /** The caller may no longer pull the model (403): its local records and cursor are gone */
+    forbidden: boolean;
+    /** The server answered 401: sign in again. Nothing was applied, nothing was discarded (§4) */
+    needsLogin: boolean;
+    /** The server could not be reached */
+    offline: boolean;
+    rejected: LtSyncPushResult[];
+    /** A `410` made the client drop its local records and pull everything again (§8) */
+    resynced: boolean;
+    /** Changes the server answered `retry`; they go out again with the next sync */
+    retried: number;
+    /** The server asked to slow down (429 / 503): milliseconds until the next attempt */
+    retryAfterMs?: number;
+}
+/** Module options (`ltExtensions.sync`) */
+export interface LtSyncModuleOptions {
+    /** Sync base path (default: '/sync' — must match the nest-server sync module) */
+    basePath?: string;
+    /** Enable the offline-sync composable and the sign-out cleanup (default: false) */
+    enabled?: boolean;
+}
+/** Options of `useLtOfflineSync()` */
+export interface UseLtOfflineSyncOptions<T = Record<string, unknown>> {
+    /** Sync on start, on `online`, on focus and after a hint (default: true). `false` leaves it to `sync()` */
+    auto?: boolean;
+    /** Listen for the server's hints (`GET <basePath>/hints`, §9) while the tab is visible (default: true) */
+    hints?: boolean;
+    /** The id format the model declares (default: 'objectId') */
+    idFormat?: LtSyncIdFormat;
+    /** Resolve a conflict yourself; without it the server's state wins */
+    onConflict?: (conflict: LtSyncConflict<T>) => LtSyncConflictResolution<T> | Promise<LtSyncConflictResolution<T>>;
+    /** Records per pull page (default: 200; the server caps it, 1000 at most) */
+    pageLimit?: number;
+    /** Restrict pull and push to one tenant (`X-Tenant-Id`, §4); records and unsent changes are kept per tenant */
+    tenantId?: string;
+}
+/** What `useLtOfflineSync()` returns */
+export interface UseLtOfflineSyncReturn<T = Record<string, unknown>> {
+    /** Conflicts of the last sync, after they were resolved */
+    conflicts: Readonly<Ref<LtSyncPushResult[]>>;
+    /** Create a record with a client id (§3); it waits in the outbox until a sync sends it */
+    create: (data: T) => Promise<LtSyncRecord<T>>;
+    /** The last unexpected error (not offline, not 401) */
+    error: Readonly<Ref<Error | null>>;
+    /** The caller may no longer pull this model (403). Unsent changes cannot be pushed under this account */
+    forbidden: Readonly<Ref<boolean>>;
+    /** One local record, a tombstone included */
+    get: (id: string) => Promise<LtSyncRecord<T> | undefined>;
+    /** Time of the last sync that reached the server */
+    lastSyncedAt: Readonly<Ref<Date | null>>;
+    /** The server answered 401. Nothing was discarded; the next sync after signing in sends everything */
+    needsLogin: Readonly<Ref<boolean>>;
+    /** The browser is offline, or the last request could not reach the server */
+    offline: Readonly<Ref<boolean>>;
+    /** Unsent local changes of this model */
+    pendingCount: Readonly<Ref<number>>;
+    /** The live local records, sorted by id. Empty while no user is signed in */
+    records: Readonly<Ref<readonly LtSyncRecord<T>[]>>;
+    /** Changes the server rejected in the last sync; they are dropped and the record returns to the server's state (§7) */
+    rejected: Readonly<Ref<LtSyncPushResult[]>>;
+    /** Delete a record: a tombstone on the server (a hard delete is not reachable through sync) */
+    remove: (id: string) => Promise<void>;
+    /** Push the outbox, then pull until the server has nothing more */
+    sync: () => Promise<LtSyncResult>;
+    /** A sync of this model is running in this tab */
+    syncing: Readonly<Ref<boolean>>;
+    /** Change fields of a record */
+    update: (id: string, data: Partial<T>) => Promise<LtSyncRecord<T>>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.20.1",
+  "version": "1.22.0",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",
@@ -102,24 +102,25 @@
   "devDependencies": {
     "@better-auth/passkey": "1.7.12",
     "@nuxt/module-builder": "1.0.3",
-    "@nuxt/schema": "4.6.3",
+    "@nuxt/schema": "4.6.4",
     "@nuxt/ui": "4.12.0",
     "@playwright/test": "1.64.1",
-    "@types/node": "26.6.5",
-    "@vitest/coverage-v8": "5.0.5",
+    "@types/node": "26.6.6",
+    "@vitest/coverage-v8": "5.1.0",
     "@vue/server-renderer": "3.5.44",
     "better-auth": "1.7.12",
     "cross-spawn": "7.0.6",
+    "fake-indexeddb": "6.2.7",
     "happy-dom": "21.0.4",
-    "nuxt": "4.6.3",
+    "nuxt": "4.6.4",
     "oxfmt": "0.75.0",
     "oxlint": "1.90.0",
     "oxlint-tsgolint": "7.0.2005",
     "reka-ui": "2.11.0",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
-    "vitest": "5.0.5",
-    "vue-tsc": "3.3.13"
+    "vitest": "5.1.0",
+    "vue-tsc": "3.3.14"
   },
   "keywords": [
     "nuxt",
@@ -138,5 +139,5 @@
     "node": ">= 22",
     "pnpm": "^11.0.0"
   },
-  "packageManager": "pnpm@11.28.9+sha512.35421cea2720eca3f5ad722b67e8ef18f4d3cd4745ed2fcfeb0dc288d4e9437fad3870d91ee6e83f268f0f6f7e0f62723317b19617bb45ee4333172ef51159f8"
+  "packageManager": "pnpm@11.28.10+sha512.672216f06e15c109b85471d49d3fbed17e6f03ead258df08c2bf5b4a5c33321ebfbf59476bce81325efada16ace0ac78548fd0bfcd7a51369e939182a3dd50e4"
 }