@proteinjs/db 1.34.3 → 1.35.0

package/dist/src/source/SourceRecordLoader.d.ts

@@ -1,14 +1,74 @@
+import { Table } from '../Table';
+/** What one boot of the sync did to one source-record table. */
+export type SourceRecordTableLoadSummary = {
+    inserts: number;
+    updates: number;
+    unchanged: number;
+    adopted: number;
+    deletes: number;
+    removedUpdates: number;
+    /** Rows stamped by a newer version of their declaring package — left exactly as they are. */
+    skippedNewer: number;
+    /** Source-loaded rows with no owner stamp that no declaration in this build claims. */
+    unowned: number;
+};
+export type SourceRecordLoadSummary = {
+    [tableName: string]: SourceRecordTableLoadSummary;
+};
 export declare class SourceRecordLoader {
     private logger;
-    load(): Promise<void>;
+    /** Memo of resolved package versions — one resolution (and at most one warning) per source. */
+    private sourceVersions;
     /**
-     * The removed-reconcile leg: rows previously loaded from source whose declaration no longer
-     * exists (`is_loaded_from_source = true AND <key> NOT IN declared`), handled per the table's
-     * `onSourceRemoved` policy — delete (default), keep, or update with a patch. The update leg
-     * applies the patch only to rows whose fields actually differ (idempotent boots), through
-     * `Db.update` so table watchers observe each write.
+     * One boot of the source-record sync, per source-record table in this build. Returns what it
+     * did to each table (also logged).
+     *
+     * Ownership model — every row has one owner, the package that declares it, ordered by that
+     * package's version:
+     * - A boot speaks only for the packages it carries. Rows owned by a package this build does
+     *   not carry are never touched: several servers running different builds against one shared
+     *   database coexist without pruning each other's rows.
+     * - Within a package, a boot speaks only for its own version or older. A row stamped by a
+     *   NEWER version of the same package is left exactly as it is — neither pruned nor rewritten —
+     *   so ordinary version skew (an older build restarting against rows a newer build added or
+     *   redefined) cannot delete or churn data. The newest version stays authoritative for
+     *   genuine removals and redefinitions.
+     * - A package in the build is authoritative for all of its rows on every table, including
+     *   tables it no longer declares anything for: dropping the last declaration is a removal.
+     * - Rows with no owner stamp (written before `source_package` existed) are claimed by the
+     *   declaration that still matches them; the rest are reported as unowned and left alone.
+     *
+     * Accepted residuals: a package removed from every build leaves its rows behind (no surviving
+     * boot carries its authority — clean up explicitly); two builds of one package at the SAME
+     * version with differing sets (uncommitted local skew) are last-writer-wins, since versions
+     * cannot order them.
+     *
+     * With no argument, every source-record table is synced (the `Db.init` full pass). Passing
+     * `onlyTable` scopes the sync to that one table — the pre-schema-sync migration phase uses
+     * this to land the migration ledger's rows before the full schema sync has run (see
+     * {@link MigrationRunner.runPreSchemaSyncMigrations}); the later full pass re-reconciles the
+     * same rows idempotently under the same ownership model.
+     */
+    load(onlyTable?: Table<any>): Promise<SourceRecordLoadSummary>;
+    /**
+     * The removed-reconcile leg: rows owned by a package this build carries, at that package's
+     * version or older, that NO package in this build still declares
+     * (`is_loaded_from_source = true AND source_package IN <build's packages> AND <key> NOT IN
+     * <build's declared keys for the table>`, minus rows stamped by a newer version of their
+     * package) are handled per the table's `onSourceRemoved` policy — delete (default), keep, or
+     * update with a patch. The update leg applies the patch only to rows whose fields actually
+     * differ (idempotent boots), through `Db.update` so table watchers observe each write.
+     * See {@link load} for the ownership model.
      */
     private reconcileRemoved;
+    /**
+     * Source-loaded rows with no owner stamp that no declaration in this build claimed on this
+     * boot (the stamp leg has already run). They predate `source_package`, or their declaring
+     * package is not in this build; nobody prunes them. Reported so they are visible, never acted
+     * on. Tables that keep removed rows (`onSourceRemoved: 'keep'`) opted out of removal
+     * semantics altogether, so there is nothing to explain there.
+     */
+    private countUnowned;
     /**
      * Resolve and validate the property the sync keys on: `id` unless the table declares
      * `sourceRecordOptions.naturalKey`. A natural key must be schema-unique (a `ColumnOptions.unique`
@@ -29,7 +89,11 @@ export declare class SourceRecordLoader {
      * triggers a rewrite. Primitive columns retain their existing semantics.
      */
     private hasChanges;
-    private getSourceRecordsMap;
+    /**
+     * Every source-record table in this build with the records declared for it, plus the set of
+     * packages that declare ANY source record in this build — the packages this boot speaks for.
+     */
+    private getDeclarations;
     /**
      * Find the first point of divergence between source and existing values.
      * Returns a description of the mismatch path, or null if they match.
@@ -58,5 +122,39 @@ export declare class SourceRecordLoader {
      * are sorted.
      */
     private canonicalStringify;
+    /** Memoized {@link resolveSourceVersion} — one resolution (and at most one warning) per source. */
+    private sourceVersion;
+    /**
+     * The declaring package's version, read from its own package.json at runtime. Resolution runs
+     * from the process cwd — the booting server's package, the one dependency tree every declaring
+     * package is reachable from (`@proteinjs/db` itself does not depend on the packages that
+     * declare records, so module-relative resolution could never find them). The package's entry
+     * is resolved (honoring exports maps, where `<pkg>/package.json` is usually not requireable),
+     * then the nearest package.json whose `name` matches is read walking up from it.
+     *
+     * Returns undefined where resolution is impossible — no Node `require` (browser bundles), or a
+     * package not resolvable from cwd. The sync then has no place in the version order for that
+     * package: it never touches its version-stamped rows, and what it writes is unversioned
+     * (see {@link isNewerStamp}). Logged once per boot so a misconfigured cwd is visible.
+     */
+    private resolveSourceVersion;
+    /**
+     * Whether a row's version stamp is strictly newer than the reconciling build's version of the
+     * same package — the guard that makes version skew of one package safe on a shared database:
+     * an older build never prunes (or flags) rows a newer build of the same package declared.
+     *
+     * Unversioned stamps (NULL — legacy rows, or builds whose version could not be resolved)
+     * carry no ordering and stay reconcilable (last-writer-wins, the pre-version behavior). A
+     * build whose OWN version is unresolvable cannot place itself in the order, so it never
+     * touches a version-stamped row — conservative: prefer leaving a removed row behind over
+     * deleting one that might be newer.
+     */
+    private isNewerStamp;
+    /**
+     * Semver comparison (major.minor.patch, prerelease-aware): negative when a < b, 0 when equal,
+     * positive when a > b, and undefined when either side does not parse as semver (unorderable —
+     * the caller treats that conservatively).
+     */
+    private compareVersions;
 }
 //# sourceMappingURL=SourceRecordLoader.d.ts.map

package/dist/src/source/SourceRecordLoader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SourceRecordLoader.d.ts","sourceRoot":"","sources":["../../../src/source/SourceRecordLoader.ts"],"names":[],"mappings":"AAYA,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAA+C;IAEvD,IAAI;IAiEV;;;;;;OAMG;YACW,gBAAgB;IAoC9B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IA+CvB;;;;;;;;;;;OAWG;YACW,UAAU;YAmBV,mBAAmB;IAwBjC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,gBAAgB;IAkDxB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,kBAAkB;CAkB3B"}
+{"version":3,"file":"SourceRecordLoader.d.ts","sourceRoot":"","sources":["../../../src/source/SourceRecordLoader.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAejC,gEAAgE;AAChE,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,6FAA6F;IAC7F,YAAY,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IAAE,CAAC,SAAS,EAAE,MAAM,GAAG,4BAA4B,CAAA;CAAE,CAAC;AAE5F,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAA+C;IAE7D,+FAA+F;IAC/F,OAAO,CAAC,cAAc,CAAyC;IAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAuGpE;;;;;;;;;OASG;YACW,gBAAgB;IA2D9B;;;;;;OAMG;YACW,YAAY;IAkB1B;;;;;OAKG;IACH,OAAO,CAAC,eAAe;IA+CvB;;;;;;;;;;;OAWG;YACW,UAAU;IAmBxB;;;OAGG;YACW,eAAe;IAmB7B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,gBAAgB;IAkDxB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,kBAAkB;IAmB1B,mGAAmG;IACnG,OAAO,CAAC,aAAa;IAQrB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,oBAAoB;IAuC5B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;IAapB;;;;OAIG;IACH,OAAO,CAAC,eAAe;CA4DxB"}