@lenne.tech/ng-base 18.1.2 → 22.0.0

package/types/lenne.tech-ng-base-sync.d.ts

@@ -0,0 +1,380 @@
+import { EnvironmentProviders, InjectionToken, Signal } from "@angular/core";
+/** The id format a sync model declares (§3). One per model, never mixed. */
+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`.
+ */
+interface LtSyncRecord<T = Record<string, unknown>> {
+  data?: T;
+  deletedAt: null | string;
+  id: string;
+  updatedAt: null | string;
+  version: number;
+}
+/** Status of one pushed change (§7) */
+type LtSyncItemStatus = 'applied' | 'conflict' | 'merged' | 'not_found' | 'rejected' | 'retry';
+/** One result of a push, in the order the changes were sent (§6.6) */
+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 */
+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).
+ */
+type LtSyncConflictResolution<T = Record<string, unknown>> = 'server' | {
+  data: Partial<T>;
+};
+/** Outcome of one sync run */
+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;
+}
+/** Options of `provideLtSync()` (runtime override `NG_PUBLIC_LT_SYNC_BASE_PATH`) */
+interface LtSyncOptions {
+  /** Sync base path (default: '/sync' — must match the nest-server sync module) */
+  basePath?: string;
+}
+/** Options of `injectLtOfflineSync()` */
+interface LtOfflineSyncOptions<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 `injectLtOfflineSync()` returns */
+interface LtOfflineSyncState<T = Record<string, unknown>> {
+  /** Conflicts of the last sync, after they were resolved */
+  conflicts: Signal<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: Signal<Error | null>;
+  /** The caller may no longer pull this model (403). Unsent changes cannot be pushed under this account */
+  forbidden: Signal<boolean>;
+  /** One local record, a tombstone included */
+  get: (id: string) => Promise<LtSyncRecord<T> | undefined>;
+  /** Time of the last sync that reached the server */
+  lastSyncedAt: Signal<Date | null>;
+  /** The server answered 401. Nothing was discarded; the next sync after signing in sends everything */
+  needsLogin: Signal<boolean>;
+  /** The browser is offline, or the last request could not reach the server */
+  offline: Signal<boolean>;
+  /** Unsent local changes of this model */
+  pendingCount: Signal<number>;
+  /** The live local records, sorted by id. Empty while no user is signed in */
+  records: Signal<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: Signal<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: Signal<boolean>;
+  /** Change fields of a record */
+  update: (id: string, data: Partial<T>) => Promise<LtSyncRecord<T>>;
+}
+/** Offline-synchronised records of one model, created by {@link injectLtOfflineSync}. */
+type LtOfflineSync<T = Record<string, unknown>> = LtOfflineSyncState<T>;
+/**
+ * Offline-first records of one model (counterpart of `useLtOfflineSync()`), bound to the current injection context.
+ *
+ * Records live in IndexedDB; changes made offline wait in an outbox and go out with the next sync.
+ * Triggers: start, `online`, window focus, `visibilitychange` (a hidden tab closes the hint stream), a server hint
+ * and every reconnect of the hint stream (protocol §9), 300 ms after a local change; backoff 1 s → 60 s. Tabs
+ * coordinate: one syncs at a time (Web Locks), the others pick up the result (BroadcastChannel); without either API
+ * it stays correct, only busier.
+ *
+ * The local data belongs to the signed-in user (`LtAuthStore.user()`, the same signal as `LtAuthService.user()`). A user change re-claims ownership of the
+ * local database: another user's data is wiped before anything is shown or pulled. `signOut()` (`LtAuthService` / `LtAuthStore`) sends
+ * what is unsent and then deletes it (hook of `provideLtSync()`). An expired session deletes nothing: after signing
+ * in again the outbox goes out without duplicates (protocol §4).
+ *
+ * During SSR or without IndexedDB it is an inert stub (empty records, mutations reject). Without a signed-in user
+ * `records` is empty and mutations throw. Everything stops when the injection context is destroyed.
+ * Requires `provideLtSync()` and `provideLtAuth()`.
+ *
+ * @example
+ * ```ts
+ * export class NotesPage {
+ *   protected readonly notes = injectLtOfflineSync<{ title: string }>('note');
+ *
+ *   add(title: string) {
+ *     return this.notes.create({ title });
+ *   }
+ * }
+ * // template: @for (note of notes.records(); track note.id) { … } · notes.pendingCount() · notes.offline()
+ * ```
+ */
+export declare function injectLtOfflineSync<T extends Record<string, unknown> = Record<string, unknown>>(model: string, options?: LtOfflineSyncOptions<T>): LtOfflineSync<T>;
+/** Resolved sync options (defaults ← `provideLtSync(options)` ← runtime `NG_PUBLIC_LT_SYNC_*`). */
+export declare const LT_SYNC_OPTIONS: InjectionToken<Required<LtSyncOptions>>;
+/**
+ * Offline sync with the nest-server sync module (≥ 12.2.0), opt-in.
+ *
+ * Configures the framework-free engine (API URL, base path, the auth-aware `LT_FETCH`) and registers a sign-out hook:
+ * before `POST /iam/sign-out` the outbox of the signed-in user is flushed (≤ 5 s), afterwards the IndexedDB is deleted,
+ * so no record, cursor or unsent change survives a sign-out. Requires `provideLtAuth()`.
+ */
+export declare function provideLtSync(options?: LtSyncOptions): EnvironmentProviders;
+/** The request could not reach the server */
+export declare class LtSyncOfflineError extends Error {
+  constructor(cause: unknown);
+}
+/** The server answered 401: the session ended. Nothing was applied, nothing is discarded (§4) */
+export declare class LtSyncUnauthorizedError extends Error {
+  constructor();
+}
+/** The server asked to slow down: 429 with `Retry-After`, or 503 (§10) */
+export declare class LtSyncBackoffError extends Error {
+  readonly status: number;
+  readonly retryAfterMs: number | undefined;
+  constructor(status: number, retryAfterMs: number | undefined);
+}
+/**
+ * An ObjectId-hex id with the random tail §3 requires: 4 timestamp bytes plus 8 bytes from a secure
+ * source, fresh for every id. A driver's default ObjectId would make the next id predictable.
+ */
+export declare function ltSyncObjectId(): string;
+/** A uuidv7: 48 bits of milliseconds, version 7, the variant, the rest random (`crypto.randomUUID()` is v4) */
+export declare function ltSyncUuidV7(): string;
+/**
+ * Environment of the engine, set by `provideLtSync()` from DI (API URL builder, sync base path, the auth-aware
+ * `LT_FETCH`). The engine itself stays framework-free; tests call {@link configureLtSync} directly.
+ */
+interface LtSyncEnvironment {
+  /** Sync base path (default `/sync`). */
+  basePath: string;
+  /** Build a full API URL for a path (`LtApiUrlService.buildUrl`). */
+  buildApiUrl: (path: string) => string;
+  /** `fetch` for every request (the auth-aware `LT_FETCH`: cookie or JWT like every other request). */
+  fetch: (input: string, init: RequestInit) => Promise<Response>;
+}
+/** Set the engine environment (done by `provideLtSync()`). */
+export declare function configureLtSync(env: Partial<LtSyncEnvironment>): void;
+/** The sync base path (default `/sync`) */
+export declare function getLtSyncBasePath(): string;
+/** A full URL for a sync path, e.g. `/note?limit=200` or `/hints?models=note` */
+export declare function buildLtSyncUrl(path: string): string;
+/** The configured fetch (auth-aware once `provideLtSync()` ran). */
+export declare function ltSyncFetch(input: string, init: RequestInit): Promise<Response>;
+/** Options of the protocol engine */
+interface LtSyncEngineOptions<T> {
+  /** `fetch` for the requests (default: the auth-aware `LT_FETCH` set by `provideLtSync()`) */
+  fetch?: (input: string, init: RequestInit) => Promise<Response>;
+  idFormat?: LtSyncIdFormat;
+  /** The model's name under the sync base path */
+  model: string;
+  onConflict?: (conflict: LtSyncConflict<T>) => LtSyncConflictResolution<T> | Promise<LtSyncConflictResolution<T>>;
+  pageLimit?: number;
+  tenantId?: string;
+}
+/** The protocol engine of one model */
+interface LtSyncEngine<T> {
+  create: (data: T) => Promise<LtSyncRecord<T>>;
+  get: (id: string) => Promise<LtSyncRecord<T> | undefined>;
+  /** The live local records, sorted by id */
+  list: () => Promise<LtSyncRecord<T>[]>;
+  readonly model: string;
+  /** Where the engine keeps its data: the model, or the model and the tenant */
+  readonly scope: string;
+  pendingCount: () => Promise<number>;
+  /** Push the outbox only — the sign-out flush. Never throws */
+  pushPending: () => Promise<void>;
+  remove: (id: string) => Promise<void>;
+  /** Push the outbox, then pull until `hasMore` is false. Never throws for offline, 401 or a backoff */
+  sync: () => Promise<LtSyncResult>;
+  update: (id: string, data: Partial<T>) => Promise<LtSyncRecord<T>>;
+}
+/**
+ * Where a model's local data lives: per model, and per tenant when one is given. A change made
+ * under one tenant must never go out with another tenant's `X-Tenant-Id` — the server stamps a
+ * create into the tenant of the header — nor show in that tenant's list.
+ */
+export declare function ltSyncScope(model: string, tenantId?: string): string;
+/** Create the protocol engine of one model and register it for the sign-out flush */
+export declare function createLtSyncEngine<T extends Record<string, unknown> = Record<string, unknown>>(options: LtSyncEngineOptions<T>): LtSyncEngine<T>;
+/**
+ * Before sign-out: send what is still unsent, for at most `timeoutMs`, never failing. Whatever
+ * did not go out is deleted with the rest afterwards — after signing out it could not be pushed
+ * under this account anyway (nest-server `SECURITY.md`).
+ *
+ * Only when the local data belongs to `userId`, the user signing out. After an expired session
+ * the outbox of the PREVIOUS user is still on the device; sent now, it would be created and
+ * changed under the current user's session and account. It is deleted unsent instead.
+ */
+export declare function flushLtSyncBeforeSignOut(userId: string | undefined, timeoutMs?: number): Promise<void>;
+/** Forget the registered engines (tests) */
+export declare function resetLtSyncEngines(): void;
+/**
+ * The hint stream of the offline sync: `GET <basePath>/hints` as server-sent events (protocol §9).
+ *
+ * Read with `fetch` and a `ReadableStream`, not `EventSource`: an EventSource cannot send an
+ * `Authorization` header, so in JWT mode (the fallback the auth-aware fetch switches to when the cookie
+ * is refused) it would never be signed in (decision E2 of DEV-3917).
+ *
+ * The server ends a stream on purpose before its first hint after the re-check interval (30 s by
+ * default) and does not replay that hint. So every (re)connect calls `onConnect`, and the caller
+ * pulls once — without it a change would wait for the next focus or start whenever hints are
+ * further apart than the interval.
+ */
+interface LtSyncHintsOptions {
+  /** `fetch` for the stream (default: the auth-aware `LT_FETCH`) */
+  fetch?: (input: string, init: RequestInit) => Promise<Response>;
+  /** The models to hear about; a model the caller may not pull simply never sends a hint */
+  models: string[];
+  /** Every (re)connect. Hints sent while disconnected are not replayed: pull once (§9) */
+  onConnect: () => void;
+  /** A change of `model` was committed: pulling is worthwhile */
+  onHint: (model: string) => void;
+  /** The stream stopped for good: the server switched SSE off (`404`) or the session ended (`401`) */
+  onStop?: (reason: 'disabled' | 'unauthorized') => void;
+  /** Restrict to one tenant (`X-Tenant-Id`) */
+  tenantId?: string;
+}
+/** One instance listening for the hints of its model */
+interface LtSyncHintSubscriber {
+  model: string;
+  onConnect: () => void;
+  onHint: () => void;
+  onStop?: (reason: 'disabled' | 'unauthorized') => void;
+  tenantId?: string;
+}
+/**
+ * Listen for the hints of a model on the ONE stream this tab keeps per tenant, for every model in
+ * use (`?models=` takes a list, §9). A stream per `useLtOfflineSync()` call would hold a connection
+ * each; over HTTP/1.1 a browser allows six per host, so six instances on one page would stall every
+ * other request to the API, sign-in and sign-out included. Answers the unsubscribe.
+ */
+export declare function subscribeLtSyncHints(subscriber: LtSyncHintSubscriber): () => void;
+/**
+ * Open the hint stream and keep it open — reconnecting after the server ends it, backing off after
+ * failures — until the returned `close()` is called or the stream stops for good (`onStop`).
+ */
+export declare function openLtSyncHints(options: LtSyncHintsOptions): () => void;
+/** Name of the database every model shares */
+export declare const LT_SYNC_DB_NAME = "lt-offline-sync";
+/** BroadcastChannel the tabs of an origin use to tell each other about changes */
+export declare const LT_SYNC_CHANNEL_NAME = "lt-offline-sync";
+/** An outbox entry: a protocol push item (§6.2) plus local bookkeeping */
+interface LtSyncOutboxItem {
+  /** Set once a push carried the item; it is never changed again, a repeat must carry the same change (§6.5) */
+  attempted?: boolean;
+  baseVersion?: number;
+  data?: Record<string, unknown>;
+  id: string;
+  mutationId: string;
+  op: 'delete' | 'upsert';
+  seq?: number;
+}
+/** What `run()` hands its callback: the transaction's operations, scoped to one model */
+interface LtSyncStoreTx {
+  addOutbox: (item: LtSyncOutboxItem) => Promise<unknown>;
+  /** Delete every local record of the model except `keepIds` */
+  clearRecords: (keepIds: Set<string>) => Promise<void>;
+  deleteMeta: (key: string) => Promise<unknown>;
+  deleteRecord: (id: string) => Promise<unknown>;
+  getMeta: <V = unknown>(key: string) => Promise<undefined | V>;
+  getRecord: (id: string) => Promise<LtSyncRecord | undefined>;
+  /** The model's unsent changes in the order they were made */
+  listOutbox: () => Promise<LtSyncOutboxItem[]>;
+  listRecords: () => Promise<LtSyncRecord[]>;
+  putOutbox: (item: LtSyncOutboxItem) => Promise<unknown>;
+  putRecord: (record: LtSyncRecord) => Promise<unknown>;
+  removeOutbox: (mutationId: string) => Promise<void>;
+  setMeta: (key: string, value: unknown) => Promise<unknown>;
+}
+/**
+ * The data no longer belongs to the user a sync run started for: signed out (database deleted) or
+ * another account claimed it. The run's write was refused, nothing of it was stored.
+ */
+export declare class LtSyncOwnerChangedError extends Error {
+  constructor();
+}
+/**
+ * Run `fn` in one read-write transaction over the scope's records, outbox and meta values. `scope`
+ * is a model, or a model and tenant (`note#<tenantId>`).
+ *
+ * With `owner`, the transaction first checks that the data still belongs to that user and refuses
+ * otherwise (`LtSyncOwnerChangedError`). A sync answer can arrive after sign-out deleted the
+ * database, or after another account claimed it — in this tab or another one. Unfenced, it would
+ * reopen the database and write the previous user's records for the next user to see.
+ */
+export declare function runLtSyncTx<R>(model: string, fn: (tx: LtSyncStoreTx) => Promise<R>, options?: {
+  owner?: string;
+}): Promise<R>;
+/** The scopes (model, or model and tenant) that hold unsent changes, in no particular order */
+export declare function listLtSyncPendingModels(): Promise<string[]>;
+/** The user the local data belongs to, if any */
+export declare function getLtSyncOwner(): Promise<string | undefined>;
+/**
+ * Bind the local data to the signed-in user, in ONE transaction. The same user keeps it. Anybody
+ * else — another user, or nobody at all while data is present — means it is not this user's: every
+ * model is wiped before anything is shown or pulled (nest-server `SECURITY.md`). Data without an
+ * owner can only be a write that outlived a sign-out, which is exactly what must not be inherited.
+ * Answers whether it wiped.
+ */
+export declare function claimLtSyncOwner(userId: string): Promise<boolean>;
+/**
+ * Delete every record, cursor and unsent change of every model — on sign-out. Other tabs close
+ * their connection on `versionchange` and are told via the channel. A sync answer arriving later
+ * finds no owner and is refused (`runLtSyncTx` with `owner`).
+ */
+export declare function deleteLtSyncDatabase(): Promise<void>;
+/** Messages the tabs exchange */
+type LtSyncMessage = {
+  scope: string;
+  type: 'changed';
+} | {
+  type: 'cleared';
+};
+export type { LtOfflineSync, LtOfflineSyncOptions, LtOfflineSyncState, LtSyncConflict, LtSyncConflictResolution, LtSyncEngine, LtSyncEngineOptions, LtSyncEnvironment, LtSyncHintSubscriber, LtSyncHintsOptions, LtSyncIdFormat, LtSyncItemStatus, LtSyncMessage, LtSyncOptions, LtSyncOutboxItem, LtSyncPushResult, LtSyncRecord, LtSyncResult, LtSyncStoreTx };