@milaboratories/pl-tree 1.5.1 → 1.5.3

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@milaboratories/pl-tree",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "Reactive pl tree state",
+  "engines": {
+    "node": ">=20.16.0"
+  },
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -20,10 +23,11 @@
     "denque": "^2.1.0",
     "utility-types": "^3.11.0",
     "zod": "~3.23.8",
-    "@milaboratories/computable": "^2.4.1",
-    "@milaboratories/pl-client": "^2.7.13",
-    "@milaboratories/pl-errors": "^1.0.2",
-    "@milaboratories/ts-helpers": "^1.1.4"
+    "@milaboratories/pl-client": "^2.7.14",
+    "@milaboratories/computable": "^2.4.3",
+    "@milaboratories/pl-error-like": "^1.12.0",
+    "@milaboratories/ts-helpers": "^1.1.5",
+    "@milaboratories/pl-errors": "^1.0.4"
   },
   "devDependencies": {
     "typescript": "~5.5.4",
@@ -37,6 +41,7 @@
   "scripts": {
     "type-check": "tsc --noEmit --composite false",
     "build": "vite build",
+    "lint": "eslint .",
     "test": "jest --runInBand",
     "do-pack": "rm -f *.tgz && pnpm pack && mv *.tgz package.tgz"
   }

package/src/accessors.ts

@@ -1,30 +1,38 @@
-import { PlTreeResource, PlTreeState } from './state';
-import {
+import type { PlTreeResource, PlTreeState } from './state';
+import type {
   AccessorProvider,
   ComputableCtx,
   ComputableHooks,
-  UsageGuard
+  UsageGuard,
 } from '@milaboratories/computable';
-import {
+import type {
   ResourceId,
-  resourceIdToString,
   ResourceType,
+  OptionalResourceId } from '@milaboratories/pl-client';
+import {
+  resourceIdToString,
   resourceTypesEqual,
   resourceTypeToString,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   NullResourceId,
-  OptionalResourceId,
-  stringifyWithResourceId
 } from '@milaboratories/pl-client';
-import { mapValueAndError, ValueAndError } from './value_and_error';
-import {
+import type { ValueAndError } from './value_and_error';
+import { mapValueAndError } from './value_and_error';
+import type {
   CommonFieldTraverseOps,
   FieldTraversalStep,
   GetFieldStep,
-  ResourceTraversalOps
+  ResourceTraversalOps,
 } from './traversal_ops';
-import { ValueOrError } from './value_or_error';
+import type { ValueOrError } from './value_or_error';
 import { parsePlError } from '@milaboratories/pl-errors';
 import { notEmpty } from '@milaboratories/ts-helpers';
+/** Error encountered during traversal in field or resource. */
+export class PlError extends Error {
+  constructor(message: string) {
+    super(message);
+  }
+}
 
 export type TreeAccessorData = {
   readonly treeProvider: () => PlTreeState;
@@ -38,25 +46,25 @@ export type TreeAccessorInstanceData = {
 
 export function isPlTreeEntry(obj: unknown): obj is PlTreeEntry {
   return (
-    typeof obj === 'object' &&
-    obj !== null &&
-    (obj as any)['__pl_tree_type_marker__'] === 'PlTreeEntry'
+    typeof obj === 'object'
+    && obj !== null
+    && (obj as any)['__pl_tree_type_marker__'] === 'PlTreeEntry'
   );
 }
 
 export function isPlTreeEntryAccessor(obj: unknown): obj is PlTreeEntryAccessor {
   return (
-    typeof obj === 'object' &&
-    obj !== null &&
-    (obj as any)['__pl_tree_type_marker__'] === 'PlTreeEntryAccessor'
+    typeof obj === 'object'
+    && obj !== null
+    && (obj as any)['__pl_tree_type_marker__'] === 'PlTreeEntryAccessor'
   );
 }
 
 export function isPlTreeNodeAccessor(obj: unknown): obj is PlTreeNodeAccessor {
   return (
-    typeof obj === 'object' &&
-    obj !== null &&
-    (obj as any)['__pl_tree_type_marker__'] === 'PlTreeNodeAccessor'
+    typeof obj === 'object'
+    && obj !== null
+    && (obj as any)['__pl_tree_type_marker__'] === 'PlTreeNodeAccessor'
   );
 }
 
@@ -66,13 +74,13 @@ export class PlTreeEntry implements AccessorProvider<PlTreeEntryAccessor> {
 
   constructor(
     private readonly accessorData: TreeAccessorData,
-    public readonly rid: ResourceId
+    public readonly rid: ResourceId,
   ) {}
 
   public createAccessor(ctx: ComputableCtx, guard: UsageGuard): PlTreeEntryAccessor {
     return new PlTreeEntryAccessor(this.accessorData, this.accessorData.treeProvider(), this.rid, {
       ctx,
-      guard
+      guard,
     });
   }
 
@@ -90,13 +98,13 @@ function getResourceFromTree(
   tree: PlTreeState,
   instanceData: TreeAccessorInstanceData,
   rid: ResourceId,
-  ops: ResourceTraversalOps
+  ops: ResourceTraversalOps,
 ): PlTreeNodeAccessor {
   const acc = new PlTreeNodeAccessor(
     accessorData,
     tree,
     tree.get(instanceData.ctx.watcher, rid),
-    instanceData
+    instanceData,
   );
 
   if (!ops.ignoreError) {
@@ -106,13 +114,14 @@ function getResourceFromTree(
   }
 
   if (
-    ops.assertResourceType !== undefined &&
-    (Array.isArray(ops.assertResourceType)
+    ops.assertResourceType !== undefined
+    && (Array.isArray(ops.assertResourceType)
       ? ops.assertResourceType.findIndex((rt) => resourceTypesEqual(rt, acc.resourceType)) === -1
       : !resourceTypesEqual(ops.assertResourceType, acc.resourceType))
   )
     throw new Error(
-      `wrong resource type ${resourceTypeToString(acc.resourceType)} but expected ${ops.assertResourceType}`
+      // eslint-disable-next-line @typescript-eslint/no-base-to-string
+      `wrong resource type ${resourceTypeToString(acc.resourceType)} but expected ${ops.assertResourceType}`,
     );
 
   return acc;
@@ -125,7 +134,7 @@ export class PlTreeEntryAccessor {
     private readonly accessorData: TreeAccessorData,
     private readonly tree: PlTreeState,
     private readonly rid: ResourceId,
-    private readonly instanceData: TreeAccessorInstanceData
+    private readonly instanceData: TreeAccessorInstanceData,
   ) {}
 
   node(ops: ResourceTraversalOps = {}): PlTreeNodeAccessor {
@@ -171,7 +180,7 @@ export class PlTreeNodeAccessor {
     private readonly accessorData: TreeAccessorData,
     private readonly tree: PlTreeState,
     private readonly resource: PlTreeResource,
-    private readonly instanceData: TreeAccessorInstanceData
+    private readonly instanceData: TreeAccessorInstanceData,
   ) {}
 
   public get id(): ResourceId {
@@ -201,7 +210,7 @@ export class PlTreeNodeAccessor {
     ...steps: [
       Omit<FieldTraversalStep, 'errorIfFieldNotSet'> & {
         errorIfFieldNotSet: true;
-      }
+      },
     ]
   ): PlTreeNodeAccessor;
   public traverse(...steps: (FieldTraversalStep | string)[]): PlTreeNodeAccessor | undefined;
@@ -213,15 +222,15 @@ export class PlTreeNodeAccessor {
     ...steps: [
       Omit<FieldTraversalStep, 'errorIfFieldNotSet'> & {
         errorIfFieldNotSet: true;
-      }
+      },
     ]
-  ): ValueOrError<PlTreeNodeAccessor, string>;
+  ): ValueOrError<PlTreeNodeAccessor, Error>;
   public traverseOrError(
     ...steps: (FieldTraversalStep | string)[]
-  ): ValueOrError<PlTreeNodeAccessor, string> | undefined;
+  ): ValueOrError<PlTreeNodeAccessor, Error> | undefined;
   public traverseOrError(
     ...steps: (FieldTraversalStep | string)[]
-  ): ValueOrError<PlTreeNodeAccessor, string> | undefined {
+  ): ValueOrError<PlTreeNodeAccessor, Error> | undefined {
     return this.traverseOrErrorWithCommon({}, ...steps);
   }
 
@@ -231,6 +240,7 @@ export class PlTreeNodeAccessor {
   ): PlTreeNodeAccessor | undefined {
     const result = this.traverseOrErrorWithCommon(commonOptions, ...steps);
     if (result === undefined) return undefined;
+
     if (!result.ok) throw result.error;
     return result.value;
   }
@@ -238,15 +248,16 @@ export class PlTreeNodeAccessor {
   public traverseOrErrorWithCommon(
     commonOptions: CommonFieldTraverseOps,
     ...steps: (FieldTraversalStep | string)[]
-  ): ValueOrError<PlTreeNodeAccessor, string> | undefined {
+  ): ValueOrError<PlTreeNodeAccessor, Error> | undefined {
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
     let current: PlTreeNodeAccessor = this;
 
     for (const _step of steps) {
-      const step: FieldTraversalStep =
-        typeof _step === 'string'
+      const step: FieldTraversalStep
+        = typeof _step === 'string'
           ? {
               ...commonOptions,
-              field: _step
+              field: _step,
             }
           : { ...commonOptions, ..._step };
 
@@ -262,17 +273,17 @@ export class PlTreeNodeAccessor {
           ok: false,
 
           // FIXME: in next tickets we'll allow Errors to be thrown.
-          error: (parsePlError(
+          error: parsePlError(
             notEmpty(next.error.getDataAsString()),
             current.id, current.resourceType, step.field,
-          ) as unknown as string),
+          ),
         };
 
       if (next.value === undefined) {
         if (step.errorIfFieldNotSet)
           return {
             ok: false,
-            error: `field have no assigned value ${step.field} of ${resourceIdToString(current.id)}`,
+            error: new Error(`field have no assigned value ${step.field} of ${resourceIdToString(current.id)}`),
           };
         // existing but unpopulated field is unstable because it must be resolved at some point
         this.onUnstableLambda('unpopulated_field:' + step.field);
@@ -392,7 +403,7 @@ export class PlTreeNodeAccessor {
 
   public getKeyValueAsJson<T = unknown>(
     key: string,
-    unstableIfNotFound: boolean = false
+    unstableIfNotFound: boolean = false,
   ): T | undefined {
     const result = this.resource.getKeyValueString(this.instanceData.ctx.watcher, key);
     if (result === undefined) {

package/src/dump.ts

@@ -1,33 +1,33 @@
-import { ExtendedResourceData } from "./state"
+import type { ExtendedResourceData } from './state';
 
 export type ResourceStats = {
-    /** Number of resources of this type */
-    count: number,
-    /** Total number of bytes in the field names of all resources of this type */
-    fieldNameBytes: number,
-    /** Total number of fields in all resources of this type */
-    fieldsCount: number,
-    /** Total number of bytes in the data of all resources of this type */
-    dataBytes: number,
-    /** Total number of key-value records in all resources of this type */
-    kvCount: number,
-    /** Total number of bytes in the key-value records of all resources of this type */
-    kvBytes: number,
-}
+  /** Number of resources of this type */
+  count: number;
+  /** Total number of bytes in the field names of all resources of this type */
+  fieldNameBytes: number;
+  /** Total number of fields in all resources of this type */
+  fieldsCount: number;
+  /** Total number of bytes in the data of all resources of this type */
+  dataBytes: number;
+  /** Total number of key-value records in all resources of this type */
+  kvCount: number;
+  /** Total number of bytes in the key-value records of all resources of this type */
+  kvBytes: number;
+};
 
 /**
  * A map of resource type statistics, keyed by the resource type name and version.
- * 
+ *
  * @type {Record<string, ResourceStats>}
  */
 export type TreeDumpStats = {
-    total: ResourceStats,
-    byResourceType: Record<`${string}/${string}`, ResourceStats>
-}
+  total: ResourceStats;
+  byResourceType: Record<`${string}/${string}`, ResourceStats>;
+};
 
 /**
  * Analyzes a collection of resources and generates statistics grouped by resource type.
- * 
+ *
  * This function processes an array of ExtendedResourceData and calculates various metrics
  * for each unique resource type, including:
  * - Count of resources
@@ -36,9 +36,9 @@ export type TreeDumpStats = {
  * - Total bytes in resource data
  * - Total number of key-value records
  * - Total bytes in key-value records
- * 
+ *
  * The statistics are organized by resource type using a key in the format "typeName/version".
- * 
+ *
  * @param dumpStats - Array of ExtendedResourceData objects to analyze
  * @returns A DumpStats object containing statistics for each resource type
  * @example
@@ -59,57 +59,57 @@ export type TreeDumpStats = {
  * ```
  */
 export function treeDumpStats(dumpStats: ExtendedResourceData[]): TreeDumpStats {
-    const stats: TreeDumpStats = {
-        total: {
-            count: 0,
-            fieldNameBytes: 0,
-            fieldsCount: 0,
-            dataBytes: 0,
-            kvCount: 0,
-            kvBytes: 0
-        },
-        byResourceType: {}
-    };
+  const stats: TreeDumpStats = {
+    total: {
+      count: 0,
+      fieldNameBytes: 0,
+      fieldsCount: 0,
+      dataBytes: 0,
+      kvCount: 0,
+      kvBytes: 0,
+    },
+    byResourceType: {},
+  };
 
-    for (const resource of dumpStats) {
-        const typeKey = `${resource.type.name}/${resource.type.version}` as const;
-        if (!stats.byResourceType[typeKey]) {
-            stats.byResourceType[typeKey] = {
-                count: 0,
-                fieldNameBytes: 0,
-                fieldsCount: 0,
-                dataBytes: 0,
-                kvCount: 0,
-                kvBytes: 0
-            };
-        }
+  for (const resource of dumpStats) {
+    const typeKey = `${resource.type.name}/${resource.type.version}` as const;
+    if (!stats.byResourceType[typeKey]) {
+      stats.byResourceType[typeKey] = {
+        count: 0,
+        fieldNameBytes: 0,
+        fieldsCount: 0,
+        dataBytes: 0,
+        kvCount: 0,
+        kvBytes: 0,
+      };
+    }
 
-        const typeStats = stats.byResourceType[typeKey];
-        typeStats.count++;
-        stats.total.count++;
+    const typeStats = stats.byResourceType[typeKey];
+    typeStats.count++;
+    stats.total.count++;
 
-        for (const field of resource.fields) {
-            typeStats.fieldNameBytes += field.name.length;
-            typeStats.fieldsCount++;
-            stats.total.fieldNameBytes += field.name.length;
-            stats.total.fieldsCount++;
-        }
+    for (const field of resource.fields) {
+      typeStats.fieldNameBytes += field.name.length;
+      typeStats.fieldsCount++;
+      stats.total.fieldNameBytes += field.name.length;
+      stats.total.fieldsCount++;
+    }
 
-        if (resource.data) {
-            const dataLength = resource.data?.length ?? 0;
-            typeStats.dataBytes += dataLength;
-            stats.total.dataBytes += dataLength;
-        }
+    if (resource.data) {
+      const dataLength = resource.data?.length ?? 0;
+      typeStats.dataBytes += dataLength;
+      stats.total.dataBytes += dataLength;
+    }
+
+    typeStats.kvCount += resource.kv.length;
+    stats.total.kvCount += resource.kv.length;
 
-        typeStats.kvCount += resource.kv.length;
-        stats.total.kvCount += resource.kv.length;
-        
-        for (const kv of resource.kv) {
-            const kvLength = kv.key.length + kv.value.length;
-            typeStats.kvBytes += kvLength;
-            stats.total.kvBytes += kvLength;
-        }
+    for (const kv of resource.kv) {
+      const kvLength = kv.key.length + kv.value.length;
+      typeStats.kvBytes += kvLength;
+      stats.total.kvBytes += kvLength;
     }
+  }
 
-    return stats;
-}
+  return stats;
+}

package/src/snapshot.ts

@@ -1,8 +1,9 @@
-import { ResourceId, ResourceType } from '@milaboratories/pl-client';
-import { Optional, Writable } from 'utility-types';
-import { ZodType, z } from 'zod';
-import { PlTreeEntry, PlTreeEntryAccessor, PlTreeNodeAccessor } from './accessors';
-import { ComputableCtx } from '@milaboratories/computable';
+import type { ResourceId, ResourceType } from '@milaboratories/pl-client';
+import type { Optional, Writable } from 'utility-types';
+import type { ZodType, z } from 'zod';
+import type { PlTreeNodeAccessor } from './accessors';
+import { PlTreeEntry, PlTreeEntryAccessor } from './accessors';
+import type { ComputableCtx } from '@milaboratories/computable';
 import { notEmpty } from '@milaboratories/ts-helpers';
 
 /**
@@ -13,7 +14,7 @@ import { notEmpty } from '@milaboratories/ts-helpers';
 export type ResourceSnapshot<
   Data = undefined,
   Fields extends Record<string, ResourceId | undefined> | undefined = undefined,
-  KV extends Record<string, unknown> | undefined = undefined
+  KV extends Record<string, unknown> | undefined = undefined,
 > = {
   readonly id: ResourceId;
   readonly type: ResourceType;
@@ -33,7 +34,7 @@ type ResourceSnapshotGeneric = ResourceSnapshot<
 export type ResourceSnapshotSchema<
   Data extends ZodType | 'raw' | undefined = undefined,
   Fields extends Record<string, boolean> | undefined = undefined,
-  KV extends Record<string, ZodType | 'raw'> | undefined = undefined
+  KV extends Record<string, ZodType | 'raw'> | undefined = undefined,
 > = {
   readonly data: Data;
   readonly fields: Fields;
@@ -44,9 +45,9 @@ export type ResourceSnapshotSchema<
 export function rsSchema<
   const Data extends ZodType | 'raw' | undefined = undefined,
   const Fields extends Record<string, boolean> | undefined = undefined,
-  const KV extends Record<string, ZodType | 'raw'> | undefined = undefined
+  const KV extends Record<string, ZodType | 'raw'> | undefined = undefined,
 >(
-  schema: Optional<ResourceSnapshotSchema<Data, Fields, KV>>
+  schema: Optional<ResourceSnapshotSchema<Data, Fields, KV>>,
 ): ResourceSnapshotSchema<Data, Fields, KV> {
   return schema as any;
 }
@@ -114,10 +115,10 @@ export function makeResourceSnapshot<Schema extends ResourceSnapshotSchemaGeneri
 export function makeResourceSnapshot<Schema extends ResourceSnapshotSchemaGeneric>(
   res: PlTreeEntry | PlTreeEntryAccessor | PlTreeNodeAccessor,
   schema: Schema,
-  ctx?: ComputableCtx
+  ctx?: ComputableCtx,
 ): InferSnapshot<Schema> {
-  const node =
-    res instanceof PlTreeEntry
+  const node
+    = res instanceof PlTreeEntry
       ? notEmpty(ctx).accessor(res).node()
       : res instanceof PlTreeEntryAccessor
         ? res.node()
@@ -138,7 +139,7 @@ export function makeResourceSnapshot<Schema extends ResourceSnapshotSchemaGeneri
       fields[fieldName] = node.traverse({
         field: fieldName,
         errorIfFieldNotSet: required,
-        stableIfNotFound: !required
+        stableIfNotFound: !required,
       })?.id;
     result.fields = fields;
   }
@@ -174,21 +175,21 @@ export type ResourceWithData = {
 export function treeEntryToResourceWithData(
   res: PlTreeEntry | ResourceWithData,
   fields: string[],
-  ctx: ComputableCtx
+  ctx: ComputableCtx,
 ): ResourceWithData {
   if (res instanceof PlTreeEntry) {
-    const node = ctx.accessor(res as PlTreeEntry).node();
+    const node = ctx.accessor(res).node();
     const info = node.resourceInfo;
 
     const fValues: [string, ResourceId | undefined][] = fields.map((name) => [
       name,
-      node.getField(name)?.value?.id
+      node.getField(name)?.value?.id,
     ]);
 
     return {
       ...info,
       fields: new Map(fValues),
-      data: node.getData() ?? new Uint8Array()
+      data: node.getData() ?? new Uint8Array(),
     };
   }
 
@@ -206,16 +207,16 @@ export type ResourceWithMetadata = {
 export function treeEntryToResourceWithMetadata(
   res: PlTreeEntry | ResourceWithMetadata,
   mdKeys: string[],
-  ctx: ComputableCtx
+  ctx: ComputableCtx,
 ): ResourceWithMetadata {
   if (!(res instanceof PlTreeEntry)) return res;
 
-  const node = ctx.accessor(res as PlTreeEntry).node();
+  const node = ctx.accessor(res).node();
   const info = node.resourceInfo;
   const mdEntries: [string, any][] = mdKeys.map((k) => [k, node.getKeyValue(k)]);
 
   return {
     ...info,
-    metadata: Object.fromEntries(mdEntries)
+    metadata: Object.fromEntries(mdEntries),
   };
 }