@milaboratories/pl-tree 1.13.6 → 1.14.0

package/dist/traversal_ops.d.ts

@@ -1,7 +1,6 @@
 import { FieldType, ResourceType } from "@milaboratories/pl-client";
-
 //#region src/traversal_ops.d.ts
-type CommonTraversalOps = {
+export type CommonTraversalOps = {
   /**
    * Don't terminate chain if current resource or field has an error associated
    * with, by default resource or field error will be thrown. If field has error
@@ -10,13 +9,14 @@ type CommonTraversalOps = {
    * */
   ignoreError?: boolean;
 };
-type CommonFieldTraverseOps = {
+export type CommonFieldTraverseOps = {
   /**
    * Valid only if {@link assertFieldType} is defined and equal to 'Input',
    * 'Service' or 'Output'. By default, if field is not found, and corresponding
    * field list is locked, call will fail with exception.
    * */
-  allowPermanentAbsence?: boolean; /** Will not mark current context as unstable, if field is not found. */
+  allowPermanentAbsence?: boolean;
+  /** Will not mark current context as unstable, if field is not found. */
   stableIfNotFound?: boolean;
   /**
    * If encounter field with error and no value, will silently terminate the
@@ -24,16 +24,19 @@ type CommonFieldTraverseOps = {
    * */
   pureFieldErrorToUndefined?: boolean;
 };
-type ResourceTraversalOps = CommonTraversalOps & {
+export type ResourceTraversalOps = CommonTraversalOps & {
   /**
    * Assert resource type of the resource the fields points to. Call will fail
    * with exception if this assertion is not fulfilled.
    * */
   assertResourceType?: ResourceType | ResourceType[];
 };
-type GetFieldStep = CommonFieldTraverseOps & {
-  /** Field name */field: string; /** Field must exist, if this option is set, instead error will be thrown */
-  errorIfFieldNotFound?: boolean; /** Field must be resolved into resource if this option is set, instead error will be thrown */
+export type GetFieldStep = CommonFieldTraverseOps & {
+  /** Field name */
+  field: string;
+  /** Field must exist, if this option is set, instead error will be thrown */
+  errorIfFieldNotFound?: boolean;
+  /** Field must be resolved into resource if this option is set, instead error will be thrown */
   errorIfFieldNotSet?: boolean;
   /**
    * Assert field type. Call will fail with exception if this assertion is not
@@ -41,7 +44,6 @@ type GetFieldStep = CommonFieldTraverseOps & {
    * */
   assertFieldType?: FieldType;
 };
-type FieldTraversalStep = GetFieldStep & ResourceTraversalOps;
+export type FieldTraversalStep = GetFieldStep & ResourceTraversalOps;
 //#endregion
-export { CommonFieldTraverseOps, CommonTraversalOps, FieldTraversalStep, GetFieldStep, ResourceTraversalOps };
 //# sourceMappingURL=traversal_ops.d.ts.map

package/dist/traversal_ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"traversal_ops.d.ts","names":[],"sources":["../src/traversal_ops.ts"],"mappings":";;;KAEY,kBAAA;;AAAZ;;;;AAOa;EAAX,WAAW;AAAA;AAAA,KAGD,sBAAA;EAAsB;;;;;EAMhC,qBAAA,YAYU;EATV,gBAAA;;;;;EAMA,yBAAA;AAAA;AAAA,KAGU,oBAAA,GAAuB,kBAAA;EAKjC;;;;EAAA,kBAAA,GAAqB,YAAA,GAAe,YAAA;AAAA;AAAA,KAG1B,YAAA,GAAe,sBAAA;mBAEzB,KAAA,UAFyB;EAKzB,oBAAA;EAGA,kBAAA;EAMA;;;AAA2B;EAA3B,eAAA,GAAkB,SAAS;AAAA;AAAA,KAGjB,kBAAA,GAAqB,YAAA,GAAe,oBAAoB"}
+{"version":3,"file":"traversal_ops.d.ts","names":[],"sources":["../src/traversal_ops.ts"],"mappings":";;YAEY;;;;;;;EAOV;;YAGU;;;;;;EAMV;;EAGA;;;;;EAMA;;YAGU,uBAAuB;;;;;EAKjC,qBAAqB,eAAe;;YAG1B,eAAe;;EAEzB;;EAGA;;EAGA;;;;;EAMA,kBAAkB;;YAGR,qBAAqB,eAAe"}

package/dist/value_and_error.d.ts

@@ -1,10 +1,9 @@
 //#region src/value_and_error.d.ts
-interface ValueAndError<T> {
+export interface ValueAndError<T> {
   value?: T;
   error?: T;
 }
-declare function mapValueAndErrorIfDefined<T1, T2>(input: ValueAndError<T1> | undefined, mapping: (v: T1) => T2): ValueAndError<T2> | undefined;
-declare function mapValueAndError<T1, T2>(input: ValueAndError<T1>, mapping: (v: T1) => T2): ValueAndError<T2>;
+export declare function mapValueAndErrorIfDefined<T1, T2>(input: ValueAndError<T1> | undefined, mapping: (v: T1) => T2): ValueAndError<T2> | undefined;
+export declare function mapValueAndError<T1, T2>(input: ValueAndError<T1>, mapping: (v: T1) => T2): ValueAndError<T2>;
 //#endregion
-export { ValueAndError, mapValueAndError, mapValueAndErrorIfDefined };
 //# sourceMappingURL=value_and_error.d.ts.map

package/dist/value_and_error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value_and_error.d.ts","names":[],"sources":["../src/value_and_error.ts"],"mappings":";UAAiB,aAAA;EACf,KAAA,GAAQ,CAAA;EACR,KAAA,GAAQ,CAAC;AAAA;AAAA,iBAGK,yBAAA,SACd,KAAA,EAAO,aAAA,CAAc,EAAA,eACrB,OAAA,GAAU,CAAA,EAAG,EAAA,KAAO,EAAA,GACnB,aAAA,CAAc,EAAA;AAAA,iBAKD,gBAAA,SAAyB,KAAA,EAAO,aAAA,CAAc,EAAA,GAAK,OAAA,GAAU,CAAA,EAAG,EAAA,KAAO,EAAA,GAAE,aAAA,CAAA,EAAA"}
+{"version":3,"file":"value_and_error.d.ts","names":[],"sources":["../src/value_and_error.ts"],"mappings":";iBAAiB,cAAc;EAC7B,QAAQ;EACR,QAAQ;;wBAGM,0BAA0B,IAAI,IAC5C,OAAO,cAAc,iBACrB,UAAU,GAAG,OAAO,KACnB,cAAc;wBAKD,iBAAiB,IAAI,IAAI,OAAO,cAAc,KAAK,UAAU,GAAG,OAAO,KAAE,cAAA"}

package/dist/value_or_error.d.ts

@@ -1,5 +1,5 @@
 //#region src/value_or_error.d.ts
-type ValueOrError<V, E> = {
+export type ValueOrError<V, E> = {
   ok: true;
   value: V;
 } | {
@@ -7,5 +7,4 @@ type ValueOrError<V, E> = {
   error: E;
 };
 //#endregion
-export { ValueOrError };
 //# sourceMappingURL=value_or_error.d.ts.map

package/dist/value_or_error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value_or_error.d.ts","names":[],"sources":["../src/value_or_error.ts"],"mappings":";KAAY,YAAA;EAEN,EAAA;EACA,KAAA,EAAO,CAAA;AAAA;EAGP,EAAA;EACA,KAAA,EAAO,CAAC;AAAA"}
+{"version":3,"file":"value_or_error.d.ts","names":[],"sources":["../src/value_or_error.ts"],"mappings":";YAAY,aAAa,GAAG;EAEtB;EACA,OAAO;;EAGP;EACA,OAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-tree",
-  "version": "1.13.6",
+  "version": "1.14.0",
   "description": "Reactive pl tree state",
   "files": [
     "./dist/**/*",
@@ -22,18 +22,18 @@
     "utility-types": "^3.11.0",
     "zod": "~3.25.76",
     "@milaboratories/computable": "2.9.8",
-    "@milaboratories/pl-errors": "1.4.35",
     "@milaboratories/ts-helpers": "1.8.6",
-    "@milaboratories/pl-client": "3.14.6"
+    "@milaboratories/pl-errors": "1.4.36",
+    "@milaboratories/pl-client": "3.14.7"
   },
   "devDependencies": {
     "@types/node": "~24.5.2",
     "@vitest/coverage-istanbul": "^4.1.3",
-    "typescript": "~5.9.3",
+    "typescript": "7.0.2",
     "vitest": "^4.1.3",
-    "@milaboratories/build-configs": "2.0.0",
     "@milaboratories/ts-configs": "1.4.0",
-    "@milaboratories/ts-builder": "1.6.2"
+    "@milaboratories/build-configs": "2.0.1",
+    "@milaboratories/ts-builder": "1.7.1"
   },
   "engines": {
     "node": ">=22.19.0"

package/src/index.ts

@@ -3,6 +3,7 @@ export * from "./state";
 export * from "./sync";
 export * from "./accessors";
 export * from "./snapshot";
+export * from "./persisted_tree";
 export * from "./synchronized_tree";
 export * from "./value_and_error";
 export * from "./value_or_error";

package/src/persisted_tree.test.ts

@@ -0,0 +1,291 @@
+import { describe, expect, test } from "vitest";
+import type { FinalResourceDataPredicate } from "@milaboratories/pl-client";
+import { createSignedResourceId, toResourceSignature } from "@milaboratories/pl-client";
+import type { ExtendedResourceData } from "./state";
+import { PlTreeState } from "./state";
+import { constructTreeLoadingRequest } from "./sync";
+import {
+  captureTreeState,
+  decodePersistedTree,
+  encodePersistedTree,
+  PERSISTED_TREE_SCHEMA_VERSION,
+  readPersistedTreeHeader,
+  restoreTreeState,
+} from "./persisted_tree";
+import {
+  dField,
+  iField,
+  TestDynamicRootState1,
+  TestStructuralResourceState1,
+  TestValueResourceState1,
+} from "./test_utils";
+
+const sig = (hex: string) => toResourceSignature(Buffer.from(hex, "hex"));
+
+/** Ids here carry real signature bytes, unlike the shared test fixtures, so the
+ *  global-id / signature split is actually exercised rather than trivially satisfied. */
+const rid = (id: bigint, signature = "a1b2c3d4") => createSignedResourceId(id, sig(signature));
+
+const RootSignature = sig("deadbeef");
+const RootId = createSignedResourceId(1000001n, RootSignature);
+
+/** The shared fixtures use resource types `DefaultFinalResourceDataPredicate` does not know,
+ *  so it settles nothing and the tree has no final/non-final split to test. Trusting the
+ *  backend's derived flag instead gives one, which is what the loading request is built from. */
+const finalByFlag: FinalResourceDataPredicate = (r) => r.final;
+
+/** A tree with a settled branch, an unsettled branch, data, kv, a dynamic field pointing at
+ *  a value, and an unresolved field. Enough shape that a codec losing a distinction the tree
+ *  cares about shows up as a different loading request. */
+function buildPopulatedTree(): PlTreeState {
+  const tree = new PlTreeState(RootId, finalByFlag);
+  tree.updateFromResourceData([
+    {
+      ...TestDynamicRootState1,
+      id: RootId,
+      fields: [dField("settled", rid(10n)), dField("running", rid(20n)), dField("pending")],
+    },
+    {
+      ...TestStructuralResourceState1,
+      id: rid(10n),
+      inputsLocked: true,
+      outputsLocked: true,
+      resourceReady: true,
+      final: true,
+      fields: [iField("payload", rid(11n))],
+      kv: [
+        { key: "meta", value: Buffer.from('{"n":1}') },
+        { key: "binary", value: Uint8Array.from([0, 1, 2, 255]) },
+      ],
+    },
+    {
+      ...TestValueResourceState1,
+      id: rid(11n),
+      data: Buffer.from("settled payload"),
+    },
+    {
+      ...TestStructuralResourceState1,
+      id: rid(20n),
+      fields: [iField("payload"), dField("progress", rid(21n))],
+    },
+    {
+      ...TestValueResourceState1,
+      id: rid(21n),
+      data: Buffer.from("in progress"),
+    },
+  ]);
+  return tree;
+}
+
+/** The claim the whole design rests on: what comes back addresses the backend the same way
+ *  the original did. Compared as sorted arrays because neither the seed order nor the skip
+ *  set's iteration order is part of the contract. */
+function loadingRequestOf(tree: PlTreeState) {
+  const req = constructTreeLoadingRequest(tree);
+  return {
+    seeds: [...req.seedResources].sort(),
+    skips: [...req.finalResources].sort(),
+  };
+}
+
+async function roundTrip(tree: PlTreeState, compress?: boolean): Promise<PlTreeState> {
+  const captured = captureTreeState(tree, RootSignature);
+  const bytes = await encodePersistedTree(captured, { compress });
+
+  const decoded = await decodePersistedTree(bytes);
+  expect(decoded.ok).toBe(true);
+  if (!decoded.ok) throw new Error("unreachable");
+
+  const restored = restoreTreeState(decoded.value, finalByFlag);
+  expect(restored).toBeDefined();
+  return restored!;
+}
+
+describe("the contract", () => {
+  test.for([true, false])(
+    "restored tree builds the same loading request (compress: %s)",
+    async (compress) => {
+      const original = buildPopulatedTree();
+      const restored = await roundTrip(original, compress);
+
+      const expected = loadingRequestOf(original);
+      // Guards against a vacuous pass: an empty tree would match trivially.
+      expect(expected.seeds.length).toBeGreaterThan(0);
+      expect(expected.skips.length).toBeGreaterThan(0);
+
+      expect(loadingRequestOf(restored)).toStrictEqual(expected);
+    },
+  );
+
+  test("restored tree holds the same resource states", async () => {
+    const original = buildPopulatedTree();
+    const restored = await roundTrip(original);
+
+    // Byte payloads are compared as plain arrays: the decoder hands back Uint8Array views
+    // while the fixtures were built from Buffers, and strict equality would read that
+    // prototype difference as a difference in state.
+    const asBytes = (b?: Uint8Array) => (b === undefined ? undefined : [...b]);
+    const normalize = (r: ExtendedResourceData) => ({
+      ...r,
+      data: asBytes(r.data),
+      kv: r.kv.map((e) => ({ key: e.key, value: asBytes(e.value) })),
+    });
+    const states = (tree: PlTreeState) =>
+      tree
+        .dumpState()
+        .map(normalize)
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+    expect(states(restored)).toStrictEqual(states(original));
+  });
+
+  test("roots survive the round trip", async () => {
+    const original = buildPopulatedTree();
+    const restored = await roundTrip(original);
+    expect([...restored.roots]).toStrictEqual([...original.roots]);
+  });
+
+  test("finality is recomputed, not read from the file", async () => {
+    const original = buildPopulatedTree();
+    const captured = captureTreeState(original, RootSignature);
+    const decoded = await decodePersistedTree(await encodePersistedTree(captured));
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) throw new Error("unreachable");
+
+    // A predicate that settles nothing must yield a tree that skips nothing, even though
+    // the file says otherwise. The file's finality is an artefact of the predicate in force
+    // when it was written, and the two are allowed to disagree.
+    const restored = restoreTreeState(decoded.value, () => false);
+    expect(restored).toBeDefined();
+    expect(constructTreeLoadingRequest(restored!).finalResources.size).toBe(0);
+    expect(constructTreeLoadingRequest(original).finalResources.size).toBeGreaterThan(0);
+  });
+});
+
+describe("the witness", () => {
+  test("is readable without inflating the payload", async () => {
+    const captured = captureTreeState(buildPopulatedTree(), RootSignature);
+    const bytes = await encodePersistedTree(captured);
+
+    const header = readPersistedTreeHeader(bytes);
+    expect(header.ok).toBe(true);
+    if (!header.ok) throw new Error("unreachable");
+
+    expect(header.value.schemaVersion).toBe(PERSISTED_TREE_SCHEMA_VERSION);
+    expect(Buffer.from(header.value.witness).equals(Buffer.from(RootSignature))).toBe(true);
+  });
+});
+
+describe("a snapshot that cannot be read", () => {
+  const encoded = async () =>
+    await encodePersistedTree(captureTreeState(buildPopulatedTree(), RootSignature));
+
+  test("a foreign file is not a snapshot", async () => {
+    const result = await decodePersistedTree(Buffer.from("this is not a tree snapshot at all"));
+    expect(result).toStrictEqual({ ok: false, reason: "not-a-snapshot" });
+  });
+
+  test("an empty file is not a snapshot", async () => {
+    expect(await decodePersistedTree(Buffer.alloc(0))).toStrictEqual({
+      ok: false,
+      reason: "not-a-snapshot",
+    });
+  });
+
+  test("a truncated file is rejected rather than replayed", async () => {
+    const bytes = await encoded();
+    const result = await decodePersistedTree(bytes.subarray(0, bytes.length - 32));
+    expect(result.ok).toBe(false);
+    if (result.ok) throw new Error("unreachable");
+    expect(["truncated", "checksum"]).toContain(result.reason);
+  });
+
+  test("a damaged payload fails its checksum", async () => {
+    const bytes = Buffer.from(await encoded());
+    // Flip a bit inside the payload, leaving the header and the length trailer intact.
+    const target = Math.floor(bytes.length / 2);
+    bytes[target] = bytes[target] ^ 0xff;
+
+    expect(await decodePersistedTree(bytes)).toStrictEqual({ ok: false, reason: "checksum" });
+  });
+
+  test("a payload that inflates past the ceiling is refused, not inflated", async () => {
+    // The checksum only says the compressed bytes are the ones that were written, so a
+    // replaced file can be consistent and still inflate to far more than a snapshot can be.
+    const bytes = await encoded();
+    expect(await decodePersistedTree(bytes, { maxPayloadBytes: 16 })).toStrictEqual({
+      ok: false,
+      reason: "checksum",
+    });
+  });
+
+  test("an unknown schema version loads as absent", async () => {
+    const bytes = Buffer.from(await encoded());
+    bytes.writeUInt16LE(PERSISTED_TREE_SCHEMA_VERSION + 1, 4);
+
+    expect(await decodePersistedTree(bytes)).toStrictEqual({ ok: false, reason: "unknown-schema" });
+    expect(readPersistedTreeHeader(bytes)).toStrictEqual({ ok: false, reason: "unknown-schema" });
+  });
+
+  test("every truncation point is a clean failure, never a throw", async () => {
+    const bytes = await encoded();
+    for (let length = 0; length < bytes.length; length++) {
+      const result = await decodePersistedTree(bytes.subarray(0, length));
+      expect(result.ok).toBe(false);
+    }
+  });
+});
+
+describe("a snapshot that decodes but cannot be applied", () => {
+  test("a dangling reference leaves no tree and does not throw", async () => {
+    const tree = buildPopulatedTree();
+    const captured = captureTreeState(tree, RootSignature);
+
+    // Drop a resource that others still point at. The codec has no opinion on this; the
+    // state-update call is what refuses it, which is the point of reusing that path.
+    const dangling = {
+      ...captured,
+      resources: captured.resources.filter((r) => r.id !== rid(11n)),
+    };
+    const decoded = await decodePersistedTree(await encodePersistedTree(dangling));
+    expect(decoded.ok).toBe(true);
+    if (!decoded.ok) throw new Error("unreachable");
+
+    expect(restoreTreeState(decoded.value, finalByFlag)).toBeUndefined();
+  });
+
+  test("a live tree survives a failed restore", async () => {
+    const live = buildPopulatedTree();
+    const before = loadingRequestOf(live);
+
+    const captured = captureTreeState(live, RootSignature);
+    const decoded = await decodePersistedTree(
+      await encodePersistedTree({
+        ...captured,
+        resources: captured.resources.filter((r) => r.id !== rid(11n)),
+      }),
+    );
+    if (!decoded.ok) throw new Error("unreachable");
+    expect(restoreTreeState(decoded.value, finalByFlag)).toBeUndefined();
+
+    // The throwaway tree absorbed the invalidation, so the working tree is untouched.
+    expect(live.isValid).toBe(true);
+    expect(loadingRequestOf(live)).toStrictEqual(before);
+  });
+});
+
+describe("capture", () => {
+  test("refuses an invalidated tree", () => {
+    const tree = buildPopulatedTree();
+    tree.invalidateTree("test");
+    expect(() => captureTreeState(tree, RootSignature)).toThrow(/invalidated/);
+  });
+
+  test("an empty tree round trips", async () => {
+    const empty = new PlTreeState(RootId, finalByFlag);
+    const restored = await roundTrip(empty);
+    expect(loadingRequestOf(restored)).toStrictEqual(loadingRequestOf(empty));
+    // An unmaterialized root is still seeded, which is how a cold tree starts.
+    expect(loadingRequestOf(restored).seeds).toStrictEqual([RootId]);
+  });
+});