@milaboratories/pl-client 3.4.2 → 3.6.0

package/src/core/tree_filter.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test } from "vitest";
+import { treeFilter, FilterOperatorType, FilterProperty } from "./tree_filter";
+import type { Filter } from "./tree_filter";
+
+describe("treeFilter builders — wire shape", () => {
+  // ── Leaf helpers ───────────────────────────────────────────────────────────
+
+  test("resourceTypeEq produces EQUAL / RESOURCE_TYPE / stringValue", () => {
+    const f = treeFilter.resourceTypeEq("Blob");
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.RESOURCE_TYPE,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "stringValue", stringValue: "Blob" },
+    });
+  });
+
+  test("resourceTypeMatch produces MATCH / RESOURCE_TYPE / stringValue", () => {
+    const f = treeFilter.resourceTypeMatch("^Blob/");
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.RESOURCE_TYPE,
+      operator: FilterOperatorType.MATCH,
+      value: { oneofKind: "stringValue", stringValue: "^Blob/" },
+    });
+  });
+
+  test("fieldNameEq produces EQUAL / FIELD_NAME / stringValue", () => {
+    const f = treeFilter.fieldNameEq("output");
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.FIELD_NAME,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "stringValue", stringValue: "output" },
+    });
+  });
+
+  test("fieldNameMatch produces MATCH / FIELD_NAME / stringValue", () => {
+    const f = treeFilter.fieldNameMatch("^__service");
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.FIELD_NAME,
+      operator: FilterOperatorType.MATCH,
+      value: { oneofKind: "stringValue", stringValue: "^__service" },
+    });
+  });
+
+  test("isFinal(true) produces EQUAL / IS_FINAL / boolValue:true", () => {
+    const f = treeFilter.isFinal(true);
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.IS_FINAL,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: true },
+    });
+  });
+
+  test("isFinal(false) produces EQUAL / IS_FINAL / boolValue:false", () => {
+    const f = treeFilter.isFinal(false);
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.IS_FINAL,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: false },
+    });
+  });
+
+  test("allOutputsFinal(true) produces EQUAL / ALL_OUTPUTS_FINAL / boolValue:true", () => {
+    const f = treeFilter.allOutputsFinal(true);
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.ALL_OUTPUTS_FINAL,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: true },
+    });
+  });
+
+  test("resourceReadyForCalculation(true) produces EQUAL / RESOURCE_READY_FOR_CALCULATION / boolValue:true", () => {
+    const f = treeFilter.resourceReadyForCalculation(true);
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.RESOURCE_READY_FOR_CALCULATION,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: true },
+    });
+  });
+
+  test("isDuplicate(false) produces EQUAL / IS_DUPLICATE / boolValue:false", () => {
+    const f = treeFilter.isDuplicate(false);
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.IS_DUPLICATE,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: false },
+    });
+  });
+
+  test("hasErrors(true) produces EQUAL / HAS_ERRORS / boolValue:true", () => {
+    const f = treeFilter.hasErrors(true);
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.HAS_ERRORS,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: true },
+    });
+  });
+
+  test("outputsLocked(true) produces EQUAL / OUTPUTS_LOCKED / boolValue:true", () => {
+    const f = treeFilter.outputsLocked(true);
+    expect(f).toEqual<Filter>({
+      key: FilterProperty.OUTPUTS_LOCKED,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: true },
+    });
+  });
+
+  test("readyOrDuplicateOrError() produces OR of the three conditions", () => {
+    const f = treeFilter.readyOrDuplicateOrError();
+    expect(f.operator).toBe(FilterOperatorType.OR);
+    if (f.value.oneofKind !== "filtersValue") throw new Error("expected filtersValue");
+    const { filters } = f.value.filtersValue;
+    expect(filters).toHaveLength(3);
+    expect(filters[0]).toEqual<Filter>({
+      key: FilterProperty.RESOURCE_READY_FOR_CALCULATION,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: true },
+    });
+    expect(filters[1]).toEqual<Filter>({
+      key: FilterProperty.IS_DUPLICATE,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: true },
+    });
+    expect(filters[2]).toEqual<Filter>({
+      key: FilterProperty.HAS_ERRORS,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: true },
+    });
+  });
+
+  test("generic eq() and match() use supplied property", () => {
+    expect(treeFilter.eq(FilterProperty.RESOURCE_TYPE, "Foo")).toEqual<Filter>({
+      key: FilterProperty.RESOURCE_TYPE,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "stringValue", stringValue: "Foo" },
+    });
+    expect(treeFilter.match(FilterProperty.FIELD_NAME, "^out")).toEqual<Filter>({
+      key: FilterProperty.FIELD_NAME,
+      operator: FilterOperatorType.MATCH,
+      value: { oneofKind: "stringValue", stringValue: "^out" },
+    });
+  });
+
+  // ── Group operators ────────────────────────────────────────────────────────
+
+  test("and() wraps children in AND / filtersValue", () => {
+    const a = treeFilter.resourceTypeEq("A");
+    const b = treeFilter.resourceTypeEq("B");
+    const f = treeFilter.and(a, b);
+    expect(f).toEqual<Filter>({
+      operator: FilterOperatorType.AND,
+      value: { oneofKind: "filtersValue", filtersValue: { filters: [a, b] } },
+    });
+    // key must be absent for group operators
+    expect(f.key).toBeUndefined();
+  });
+
+  test("or() wraps children in OR / filtersValue", () => {
+    const a = treeFilter.isFinal(true);
+    const b = treeFilter.allOutputsFinal(true);
+    const f = treeFilter.or(a, b);
+    expect(f).toEqual<Filter>({
+      operator: FilterOperatorType.OR,
+      value: { oneofKind: "filtersValue", filtersValue: { filters: [a, b] } },
+    });
+  });
+
+  test("not() wraps single child in NOT / filtersValue", () => {
+    const inner = treeFilter.resourceTypeEq("Blob");
+    const f = treeFilter.not(inner);
+    expect(f).toEqual<Filter>({
+      operator: FilterOperatorType.NOT,
+      value: { oneofKind: "filtersValue", filtersValue: { filters: [inner] } },
+    });
+  });
+
+  // ── Nested composition ────────────────────────────────────────────────────
+
+  test("nested AND(RESOURCE_TYPE, IS_FINAL) round-trips correctly", () => {
+    // Mirrors the Go-side mustCompileTraverseStopRules usage:
+    // AND(RESOURCE_TYPE == "StdMap", IS_FINAL == true)
+    const f = treeFilter.and(treeFilter.resourceTypeEq("StdMap"), treeFilter.isFinal(true));
+
+    expect(f.operator).toBe(FilterOperatorType.AND);
+    expect(f.key).toBeUndefined();
+    if (f.value.oneofKind !== "filtersValue") throw new Error("expected filtersValue");
+
+    const { filters } = f.value.filtersValue;
+    expect(filters).toHaveLength(2);
+
+    expect(filters[0]).toEqual<Filter>({
+      key: FilterProperty.RESOURCE_TYPE,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "stringValue", stringValue: "StdMap" },
+    });
+    expect(filters[1]).toEqual<Filter>({
+      key: FilterProperty.IS_FINAL,
+      operator: FilterOperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: true },
+    });
+  });
+
+  test("NOT(AND(RESOURCE_TYPE, FIELD_NAME)) used in field_filters", () => {
+    // NOT( AND(RESOURCE_TYPE == "BlockPackCustom", FIELD_NAME == "template") )
+    const f = treeFilter.not(
+      treeFilter.and(
+        treeFilter.resourceTypeEq("BlockPackCustom"),
+        treeFilter.fieldNameEq("template"),
+      ),
+    );
+    expect(f.operator).toBe(FilterOperatorType.NOT);
+    if (f.value.oneofKind !== "filtersValue") throw new Error("expected filtersValue");
+    const [andNode] = f.value.filtersValue.filters;
+    expect(andNode.operator).toBe(FilterOperatorType.AND);
+    if (andNode.value.oneofKind !== "filtersValue") throw new Error("expected filtersValue");
+    expect(andNode.value.filtersValue.filters).toHaveLength(2);
+  });
+});

package/src/core/tree_filter.ts

@@ -0,0 +1,182 @@
+import type { ResourceAPI_Tree_Filter } from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
+import {
+  ResourceAPI_Tree_Filter_OperatorType,
+  ResourceAPI_Tree_Filter_Property,
+} from "../proto-grpc/github.com/milaboratory/pl/plapi/plapiproto/api";
+
+export type { ResourceAPI_Tree_Filter };
+
+/** Shorthand alias for the filter predicate type. */
+export type Filter = ResourceAPI_Tree_Filter;
+
+/** Shorthand alias for the Property enum. */
+export type Property = ResourceAPI_Tree_Filter_Property;
+
+// Re-export enum namespaces under shorter aliases so callers need not import api.ts directly.
+export { ResourceAPI_Tree_Filter_OperatorType as FilterOperatorType };
+export { ResourceAPI_Tree_Filter_Property as FilterProperty };
+
+/**
+ * Builder helpers for {@link ResourceAPI_Tree_Filter} predicates used in
+ * `ResourceAPI_Tree_Request.fieldFilter` and `traverseStopRules`.
+ *
+ * Property restrictions (not enforced here; the backend rejects invalid combinations):
+ *   - `FIELD_NAME` is only valid inside `fieldFilter`.
+ *   - `IS_FINAL`, `ALL_OUTPUTS_FINAL`, and resource-level boolean predicates are only valid inside `traverseStopRules`.
+ */
+export const treeFilter = {
+  // ── Group operators ──────────────────────────────────────────────────────
+
+  and(...children: Filter[]): Filter {
+    return {
+      operator: ResourceAPI_Tree_Filter_OperatorType.AND,
+      value: { oneofKind: "filtersValue", filtersValue: { filters: children } },
+    };
+  },
+
+  or(...children: Filter[]): Filter {
+    return {
+      operator: ResourceAPI_Tree_Filter_OperatorType.OR,
+      value: { oneofKind: "filtersValue", filtersValue: { filters: children } },
+    };
+  },
+
+  not(child: Filter): Filter {
+    return {
+      operator: ResourceAPI_Tree_Filter_OperatorType.NOT,
+      value: { oneofKind: "filtersValue", filtersValue: { filters: [child] } },
+    };
+  },
+
+  // ── Generic leaf operators ───────────────────────────────────────────────
+
+  /** Exact-match predicate on a string property. */
+  eq(prop: Property, value: string): Filter {
+    return {
+      key: prop,
+      operator: ResourceAPI_Tree_Filter_OperatorType.EQUAL,
+      value: { oneofKind: "stringValue", stringValue: value },
+    };
+  },
+
+  /** Regex-match predicate on a string property. */
+  match(prop: Property, pattern: string): Filter {
+    return {
+      key: prop,
+      operator: ResourceAPI_Tree_Filter_OperatorType.MATCH,
+      value: { oneofKind: "stringValue", stringValue: pattern },
+    };
+  },
+
+  /** Boolean-equality predicate. */
+  boolEq(prop: Property, value: boolean): Filter {
+    return {
+      key: prop,
+      operator: ResourceAPI_Tree_Filter_OperatorType.EQUAL,
+      value: { oneofKind: "boolValue", boolValue: value },
+    };
+  },
+
+  // ── Typed convenience wrappers ───────────────────────────────────────────
+
+  /** Match resources whose type string equals `name` exactly. */
+  resourceTypeEq(name: string): Filter {
+    return treeFilter.eq(ResourceAPI_Tree_Filter_Property.RESOURCE_TYPE, name);
+  },
+
+  /** Match resources whose type string satisfies the regex `pattern`. */
+  resourceTypeMatch(pattern: string): Filter {
+    return treeFilter.match(ResourceAPI_Tree_Filter_Property.RESOURCE_TYPE, pattern);
+  },
+
+  /**
+   * Match field edges whose name equals `name` exactly.
+   * Valid only inside `fieldFilter`.
+   */
+  fieldNameEq(name: string): Filter {
+    return treeFilter.eq(ResourceAPI_Tree_Filter_Property.FIELD_NAME, name);
+  },
+
+  /**
+   * Match field edges whose name satisfies the regex `pattern`.
+   * Valid only inside `fieldFilter`.
+   */
+  fieldNameMatch(pattern: string): Filter {
+    return treeFilter.match(ResourceAPI_Tree_Filter_Property.FIELD_NAME, pattern);
+  },
+
+  /**
+   * Match resources where `is_final == value`.
+   * Valid only inside `traverseStopRules`.
+   */
+  isFinal(value: boolean): Filter {
+    return treeFilter.boolEq(ResourceAPI_Tree_Filter_Property.IS_FINAL, value);
+  },
+
+  /**
+   * Match resources where `all_outputs_final == value`.
+   * Valid only inside `traverseStopRules`.
+   */
+  allOutputsFinal(value: boolean): Filter {
+    return treeFilter.boolEq(ResourceAPI_Tree_Filter_Property.ALL_OUTPUTS_FINAL, value);
+  },
+
+  /**
+   * Match resources where `resource_ready_for_calculation == value`.
+   * True when the resource is Original, inputs are locked, and all inputs are final.
+   * Valid only inside `traverseStopRules`.
+   */
+  resourceReadyForCalculation(value: boolean): Filter {
+    return treeFilter.boolEq(
+      ResourceAPI_Tree_Filter_Property.RESOURCE_READY_FOR_CALCULATION,
+      value,
+    );
+  },
+
+  /**
+   * Match resources where `is_duplicate == value`.
+   * True when the resource has a non-zero original_resource_id.
+   * Valid only inside `traverseStopRules`.
+   */
+  isDuplicate(value: boolean): Filter {
+    return treeFilter.boolEq(ResourceAPI_Tree_Filter_Property.IS_DUPLICATE, value);
+  },
+
+  /**
+   * Match resources where `has_errors == value`.
+   * True when the resource has at least one field carrying an error (aggregated
+   * has-error flag). Can be true even when the resource's own status is not
+   * Error (e.g., an Original resource with a failed input field).
+   * Valid only inside `traverseStopRules`.
+   */
+  hasErrors(value: boolean): Filter {
+    return treeFilter.boolEq(ResourceAPI_Tree_Filter_Property.HAS_ERRORS, value);
+  },
+
+  /**
+   * Match resources where `outputs_locked == value`.
+   * Valid only inside `traverseStopRules`.
+   */
+  outputsLocked(value: boolean): Filter {
+    return treeFilter.boolEq(ResourceAPI_Tree_Filter_Property.OUTPUTS_LOCKED, value);
+  },
+
+  /**
+   * Match resources that are ready-or-duplicate-or-error: mirrors the BFS
+   * `readyOrDuplicateOrError` predicate used by pl-tree to decide whether a
+   * resource subtree needs further polling.
+   *
+   * Use this as `traverseStopRules` to stop the server-side tree walk at
+   * exactly the same nodes where the client BFS would stop, eliminating
+   * unnecessary follow-up calls.
+   *
+   * Valid only inside `traverseStopRules`.
+   */
+  readyOrDuplicateOrError(): Filter {
+    return treeFilter.or(
+      treeFilter.resourceReadyForCalculation(true),
+      treeFilter.isDuplicate(true),
+      treeFilter.hasErrors(true),
+    );
+  },
+} as const;

package/src/core/type_conversion.ts

@@ -26,7 +26,7 @@ import { throwPlNotFoundError } from "./errors";
 
 const ResourceErrorField = "resourceError";
 
-function resourceIsDeleted(proto: Resource): boolean {
+export function resourceIsDeleted(proto: Resource): boolean {
   return proto.deletedTime !== undefined && proto.deletedTime.seconds !== 0n;
 }
 

package/src/core/types.ts

@@ -1,3 +1,5 @@
+/* eslint-disable eslint-js/no-restricted-syntax -- this file is the canonical place to construct SignedResourceId values; outside callers must use asSignedResourceId(). */
+
 import type { Branded } from "@milaboratories/pl-model-common";
 import { cachedDeserialize, notEmpty } from "@milaboratories/ts-helpers";
 
@@ -282,7 +284,6 @@ export function isNullSignedResourceId(
 export function isNotNullSignedResourceId(
   resourceId: OptionalSignedResourceId,
 ): resourceId is SignedResourceId {
-  // lint-allow-cast
   return resourceId !== NullSignedResourceId;
 }
 
@@ -294,10 +295,19 @@ export function ensureSignedResourceIdNotNull(
 }
 
 export function isSignedResourceId(resourceId: bigint | string): resourceId is SignedResourceId {
-  // lint-allow-cast
   return typeof resourceId === "string" && resourceId.includes("|");
 }
 
+/** Validate a string as a SignedResourceId and return it with the branded type.
+ *  Requires the format "<globalId>|<signatureHex>" with a non-empty signature. */
+export function asSignedResourceId(str: string): SignedResourceId {
+  const pipeIdx = str.indexOf("|");
+  if (pipeIdx < 0) throw new Error(`Not a signed resource id (no '|' separator): ${str}`);
+  if (pipeIdx === 0) throw new Error(`Signed resource id has empty globalId: ${str}`);
+  if (pipeIdx === str.length - 1) throw new Error(`Signed resource id has empty signature: ${str}`);
+  return str as SignedResourceId;
+}
+
 /** Encode resource signature to base64url for embedding in URL-based handles. */
 export function signatureToBase64Url(sig?: ResourceSignature): string {
   return sig && sig.length > 0 ? Buffer.from(sig).toString("base64url") : "";
@@ -326,7 +336,7 @@ export function createSignedResourceId(
   if (isNullResourceId(globalId)) throw new Error(`Null resource id.`);
 
   const sigHex = signature ? Buffer.from(signature).toString("hex") : "";
-  return `${String(globalId)}|${sigHex}` as SignedResourceId; // lint-allow-cast
+  return `${String(globalId)}|${sigHex}` as SignedResourceId;
 }
 
 export function parseSignedResourceId(resourceId: SignedResourceId): {

package/src/index.ts

@@ -9,6 +9,7 @@ export * from "./core/default_client";
 export * from "./core/unauth_client";
 export * from "./core/auth";
 export * from "./core/final";
+export * from "./core/tree_filter";
 export * from "./core/user_resources";
 export * from "./core/wire";
 export * from "./helpers/tx_helpers";

package/src/proto-grpc/github.com/googleapis/googleapis/google/rpc/status.ts

@@ -2,7 +2,7 @@
 // @generated from protobuf file "github.com/googleapis/googleapis/google/rpc/status.proto" (package "google.rpc", syntax proto3)
 // tslint:disable
 //
-// Copyright 2025 Google LLC
+// Copyright 2026 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.