@carlonicora/nextjs-jsonapi 6.13.1 → 6.14.0

package/dist/offline/index.d.ts

@@ -17,6 +17,27 @@ type ApiRequestDataTypeInterface = {
     model: new () => any;
 };
 
+interface JsonApiHydratedDataInterface {
+    jsonApi: any;
+    included: any[];
+    allData?: any[];
+}
+
+interface ApiDataInterface {
+    get included(): any[];
+    get type(): string;
+    get id(): string;
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    get self(): string | undefined;
+    get jsonApi(): any;
+    get identifier(): string;
+    generateApiUrl(params?: any): string;
+    dehydrate(): JsonApiHydratedDataInterface;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(data: any): any;
+}
+
 type OfflineChangeResolution = {
     kind: "mine" | "merged";
     /** Per conflicting field: whose value wins. */
@@ -183,6 +204,46 @@ type OfflineLinkedListFetch = {
         id: string;
     }) => string;
 };
+/** One more kind of root record beside `rootModule` (e.g. a notebook). Optional. */
+type OfflineRootKind = {
+    /** The module of the root records of this kind. Sync reads `{module}/:rootId/sync`. */
+    module: ApiRequestDataTypeInterface;
+    /** The ids of the roots of this kind to keep on the device. Throw to keep the device copy unchanged. */
+    listSyncRoots: () => Promise<string[]>;
+    /**
+     * Per record type, the full list endpoint (query string included) that downloads every record of
+     * that type under one root of this kind, built from the stored root record. Replaces the type's
+     * `fetch` mode under this kind only. Never given `updatedSince`.
+     */
+    typeEndpoints?: {
+        module: ApiRequestDataTypeInterface;
+        endpoint: (root: {
+            id: string;
+            resource: StoredRecord["resource"];
+        }) => string;
+    }[];
+    /** The module whose model reads this kind's sync answer. Default: the library's `RootSync` module (`root-syncs`). */
+    syncModule?: ApiRequestDataTypeInterface;
+};
+type LocalWriteBase = {
+    store: DeviceStore;
+    module: ApiRequestDataTypeInterface;
+    id: string;
+};
+/** What a generic local write (`afterLocalWrite`) did, inside its transaction. */
+type OfflineLocalWriteContext = (LocalWriteBase & {
+    method: "POST";
+    resource: StoredRecord["resource"];
+    previous: null;
+}) | (LocalWriteBase & {
+    method: "PUT" | "PATCH";
+    resource: StoredRecord["resource"];
+    previous: StoredRecord["resource"];
+}) | (LocalWriteBase & {
+    method: "DELETE";
+    resource: null;
+    previous: StoredRecord["resource"];
+});
 type OfflineTypeConfig = {
     module: ApiRequestDataTypeInterface;
     /**
@@ -205,6 +266,11 @@ type OfflineTypeConfig = {
     searchFields?: string[];
     /** The server's order with no `orderBy` (default `updatedAt DESC`). */
     defaultOrderBy?: string;
+    /**
+     * Called by the generic POST/PUT/PATCH/DELETE local answers inside the same transaction as the
+     * write and the enqueue (a throw rolls both back). Never called by sync or write-through.
+     */
+    afterLocalWrite?: (ctx: OfflineLocalWriteContext) => Promise<void>;
 };
 type OfflineConfig = {
     getUserId: () => string | undefined;
@@ -219,6 +285,8 @@ type OfflineConfig = {
     routes: OfflineRoute[];
     /** Ids of the root records to keep on the device. */
     listSyncRoots: () => Promise<string[]>;
+    /** More kinds of root records beside `rootModule`, each synced and kept on its own (optional). */
+    extraRootKinds?: OfflineRootKind[];
     shellPath: (locale: string) => string;
     syncIntervalMs: number;
     /**
@@ -472,6 +540,92 @@ declare function mergeResource(before: any, identity: {
     id: string;
 }, data: ResourceDocumentData): any;
 
+declare abstract class AbstractApiData implements ApiDataInterface {
+    static identifierFields: string[];
+    get identifier(): string;
+    protected _jsonApi?: any;
+    protected _included?: any[];
+    protected _id?: string;
+    protected _type?: string;
+    protected _createdAt?: Date;
+    protected _updatedAt?: Date;
+    protected _self?: string;
+    get type(): string;
+    get id(): string;
+    get self(): string | undefined;
+    get createdAt(): Date;
+    get updatedAt(): Date;
+    get included(): any[];
+    get jsonApi(): any;
+    ingestJsonApi(_data: JsonApiHydratedDataInterface): void;
+    generateApiUrl(_params?: any): string;
+    createJsonApi(_data?: any): any;
+    protected _readIncluded<T extends ApiDataInterface>(data: JsonApiHydratedDataInterface, type: string, dataType: ApiRequestDataTypeInterface): T | T[] | undefined;
+    /**
+     * Read included relationships with polymorphic type resolution.
+     * Determines the correct model class based on the JSON:API type in included data.
+     */
+    protected _readIncludedPolymorphic<T extends ApiDataInterface>(data: JsonApiHydratedDataInterface, relationshipKey: string, candidateModules: ApiRequestDataTypeInterface[]): T | T[] | undefined;
+    /**
+     * Read included relationship data and augment with relationship meta properties.
+     * Handles both single relationships (one-to-one) and array relationships (one-to-many).
+     *
+     * For single relationships: meta is read from `relationships[type].meta`
+     * For array relationships: per-item meta is read from `relationships[type].data[].meta`
+     *
+     * @param data - Hydrated JSON:API data
+     * @param type - Relationship type key (e.g., "guide", "persons")
+     * @param dataType - Module reference for rehydration
+     * @returns Related object(s) augmented with meta properties, or undefined
+     */
+    protected _readIncludedWithMeta<T extends ApiDataInterface, M extends Record<string, any>>(data: JsonApiHydratedDataInterface, type: string, dataType: ApiRequestDataTypeInterface): (T & M) | (T & M)[] | undefined;
+    /**
+     * Copies relationship meta onto a rehydrated entity as own data properties. Object.assign throws
+     * when the model declares a getter-only accessor of the same name (an app's `Chunk` with
+     * `get relevance()`); an own property shadows that getter, so the model reads the meta value.
+     */
+    private static _mergeMeta;
+    dehydrate(): JsonApiHydratedDataInterface;
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+}
+
+type RootSyncEntry = {
+    type: string;
+    id: string;
+    updatedAt: Date;
+};
+type RootSyncLink = {
+    fromType: string;
+    fromId: string;
+    toType: string;
+    toId: string;
+    kind: string;
+    props: Record<string, unknown>;
+};
+interface RootSyncInterface extends ApiDataInterface {
+    get serverTime(): Date;
+    get locked(): boolean;
+    get lockedFrom(): Date | undefined;
+    get entries(): RootSyncEntry[];
+    get links(): RootSyncLink[];
+}
+
+/** The sync answer for one root record (`root-syncs`, id = root record id). Read-only. */
+declare class RootSync extends AbstractApiData implements RootSyncInterface {
+    private _serverTime?;
+    private _locked;
+    private _lockedFrom?;
+    private _entries?;
+    private _links?;
+    get serverTime(): Date;
+    get locked(): boolean;
+    get lockedFrom(): Date | undefined;
+    get entries(): RootSyncEntry[];
+    get links(): RootSyncLink[];
+    rehydrate(data: JsonApiHydratedDataInterface): this;
+    createJsonApi(_data?: any): any;
+}
+
 /**
  * Opens the device copy of `userId` (`nja-offline-<userId>.sqlite3` in the OPFS,
  * through the worker). Only one user's file is open at a time: opening another
@@ -506,10 +660,12 @@ declare function isRootLocked(s: {
  * are replaced, and artwork images are downloaded. The sync state is stored only once every
  * fetch succeeded (or answered 403/404). A record with a waiting change is never overwritten.
  */
-declare function syncRoot(rootId: string): Promise<void>;
+declare function syncRoot(rootId: string, kind?: OfflineRootKind): Promise<void>;
 /**
- * Syncs every root record `listSyncRoots()` returns, then removes from the device the root records
- * that are no longer roots (unless they still have waiting changes). Does nothing offline.
+ * Syncs every root record of every kind (`listSyncRoots()` of the primary kind and of each
+ * `extraRootKinds` entry), then removes from the device the known root records no kind lists
+ * (unless they still have waiting changes). A kind whose list throws keeps its device copy
+ * unchanged; the primary kind's list throwing stops the sync. Does nothing offline.
  */
 declare function syncAll(): Promise<void>;
 
@@ -604,4 +760,4 @@ declare function turnOffOffline(): Promise<{
     pending: number;
 }>;
 
-export { type Conflict, type ConflictChoice, type ConflictKind, DEFAULT_DEVICE_WORKER_URL, DEFAULT_SQLITE_MODULE_URL, DEVICE_WORKER_FILE, type DeviceStore, DeviceStoreUnavailableError, type DrainResult, type ListOptions, type LocalAnswer, type LocalAnswerContext, NeedsConnectionError, OFFLINE_REPLAY_HEADER, OFFLINE_SQLITE_FILES, type OfflineAnswer, type OfflineChangeResolution, type OfflineConfig, type OfflineLinkedListFetch, type OfflineMethod, type OfflineRequest, type OfflineRoute, type OfflineState, type OfflineTypeConfig, OfflineUnavailableError, type PatternSegment, type QueueEntry, type QueueResolution, type QueueStatus, type ResourceDocumentData, type RouteMatch, SERVER_DEFAULT_ORDER_BY, type SkippedRecord, type StoredLink, type StoredRecord, type SyncState, configureOffline, deleteDeviceStore, drainQueue, errorAnswer, finishOfflineLogout, forgetOfflineStore, getOfflineConfig, getOfflineState, getOfflineStore, hasUnsentChanges, includedFor, isOfflineAvailable, isOfflineConfigured, isOfflineEnabledOnDevice, isRootLocked, linkKindFor, linkKindsOf, linksOfKind, listAnswer, localTransport, matchPattern, matchRoute, mergeResource, needsConnectionAnswer, notFoundAnswer, onUserSignedIn, openDeviceStore, openMemoryDeviceStore, orderRecords, orderedListAnswer, patternToString, prepareOfflineLogout, refreshOfflineDeviceState, resolveConflict, resourceFromDocument, resourceListAnswer, searchRecords, setDeviceStoreOpener, setOfflineState, singleAnswer, startOfflineRuntime, stopOfflineRuntime, subscribeOfflineState, syncAll, syncRoot, turnOffOffline, turnOnOffline, useConflicts, useNeedsConnection, useOfflineState, writeThrough };
+export { type Conflict, type ConflictChoice, type ConflictKind, DEFAULT_DEVICE_WORKER_URL, DEFAULT_SQLITE_MODULE_URL, DEVICE_WORKER_FILE, type DeviceStore, DeviceStoreUnavailableError, type DrainResult, type ListOptions, type LocalAnswer, type LocalAnswerContext, NeedsConnectionError, OFFLINE_REPLAY_HEADER, OFFLINE_SQLITE_FILES, type OfflineAnswer, type OfflineChangeResolution, type OfflineConfig, type OfflineLinkedListFetch, type OfflineLocalWriteContext, type OfflineMethod, type OfflineRequest, type OfflineRootKind, type OfflineRoute, type OfflineState, type OfflineTypeConfig, OfflineUnavailableError, type PatternSegment, type QueueEntry, type QueueResolution, type QueueStatus, type ResourceDocumentData, RootSync, type RouteMatch, SERVER_DEFAULT_ORDER_BY, type SkippedRecord, type StoredLink, type StoredRecord, type SyncState, configureOffline, deleteDeviceStore, drainQueue, errorAnswer, finishOfflineLogout, forgetOfflineStore, getOfflineConfig, getOfflineState, getOfflineStore, hasUnsentChanges, includedFor, isOfflineAvailable, isOfflineConfigured, isOfflineEnabledOnDevice, isRootLocked, linkKindFor, linkKindsOf, linksOfKind, listAnswer, localTransport, matchPattern, matchRoute, mergeResource, needsConnectionAnswer, notFoundAnswer, onUserSignedIn, openDeviceStore, openMemoryDeviceStore, orderRecords, orderedListAnswer, patternToString, prepareOfflineLogout, refreshOfflineDeviceState, resolveConflict, resourceFromDocument, resourceListAnswer, searchRecords, setDeviceStoreOpener, setOfflineState, singleAnswer, startOfflineRuntime, stopOfflineRuntime, subscribeOfflineState, syncAll, syncRoot, turnOffOffline, turnOnOffline, useConflicts, useNeedsConnection, useOfflineState, writeThrough };