@milaboratories/pl-model-common 1.47.2 → 1.48.0

package/src/drivers/pframe/spec/ids.ts

@@ -8,6 +8,8 @@ import {
 } from "./filtered_column";
 import {
   createPObjectId,
+  isGlobalPObjectKey,
+  isLocalPObjectKey,
   isPObjectId,
   isPObjectKey,
   LocalPObjectKey,
@@ -28,7 +30,7 @@ import {
   type ColumnOverriddenId,
   type ColumnOverriddenKey,
 } from "./overridden";
-import { canonicalizeJson } from "../../../json";
+import { canonicalizeJson, parseJsonSafely } from "../../../json";
 import { AxisSpec, PColumnSpec } from "./spec";
 import { isString } from "es-toolkit";
 
@@ -97,6 +99,194 @@ export function parseColumnIdSafely(
   }
 }
 
+/** Whether `value` is any of the five key forms a {@link ColumnUniversalId} serializes. */
+export function isColumnUniversalKey(value: unknown): value is ColumnUniversalKey {
+  return (
+    isPObjectKey(value) ||
+    isColumnFilteredKey(value) ||
+    isColumnDiscoveredKey(value) ||
+    isColumnOverriddenKey(value)
+  );
+}
+
+export function isColumnUniversalId(value: unknown): value is ColumnUniversalId {
+  const key = isString(value) ? parseJsonSafely(value, false) : false;
+  return key === false ? false : isColumnUniversalKey(key);
+}
+
+/**
+ * A JSON string with its escape padding taken off, and how many passes that took.
+ *
+ * `layers` counts the `JSON.stringify` passes *above* the encoded value: a canonical id
+ * is `layers: 0`, the same id run through `JSON.stringify` once more is `layers: 1`. Keep
+ * it to put the value back the way it was found.
+ */
+export type PeeledJsonLayers = {
+  readonly value: unknown;
+  readonly layers: number;
+};
+
+/**
+ * Take a value out of however many `JSON.stringify` passes wrapped it, or `undefined`
+ * when `s` is not JSON at all.
+ *
+ * The one definition of "how a value can be hiding inside a string" — a block id can sit
+ * under several layers of escaping, and a walk over object properties reaches none of
+ * them. Callers differ in what they do at the bottom (this deliberately says nothing
+ * about which values count as identifiers), but they must agree on the mechanics, or
+ * "what carries a block id" ends up with two answers that drift.
+ *
+ * The gate is cheap and does NOT require any marker in the body: a filtered id whose
+ * innermost leaf is a {@link LocalPObjectKey} carries no `__isRef`, so demanding one
+ * would miss it.
+ */
+export function peelJsonLayers(s: string): PeeledJsonLayers | undefined {
+  let current = s;
+  let layers = 0;
+  for (;;) {
+    const c0 = current.charCodeAt(0);
+    if (c0 !== 0x7b /* { */ && c0 !== 0x22 /* " */) return undefined;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(current);
+    } catch {
+      return undefined;
+    }
+    // A pass that yielded another string was escape padding, so peel again. The string
+    // is strictly shorter each time, which is what bounds the loop.
+    if (isString(parsed)) {
+      if (parsed.length >= current.length) return undefined;
+      current = parsed;
+      layers++;
+      continue;
+    }
+    return { value: parsed, layers };
+  }
+}
+
+/**
+ * Rewrite every block id buried inside a column id.
+ *
+ * A {@link GlobalPObjectKey} leaf names its upstream by block id, and the wrapper key forms
+ * nest by *string* id rather than by object — so a block id can sit under several layers of
+ * JSON escaping, and `queriesQualifications` carries one in a map *key*. A caller that only
+ * walks object properties never reaches any of them, which is why moving a column id between
+ * projects needs this rather than a generic walk.
+ *
+ * Recursion re-canonicalizes bottom-up, so every level is canonical afterwards — including
+ * the rebuilt `queriesQualifications`, whose keys the canonical form sorts. That is the
+ * property a textual rewrite cannot have: redirecting an id that is a map key changes what
+ * the sorted order should be, and only rebuilding restores it.
+ *
+ * Returns the input itself when no block id changed, so a caller mapping ids to themselves
+ * gets its value back byte-for-byte and never re-serializes a stored id. Any `string` is
+ * accepted for the same reason: a caller sweeping a params object cannot know which of its
+ * strings are ids, and one that is not is returned as-is.
+ *
+ * @param remapBlockId old block id → new block id. Throw from it to reject an id that cannot
+ *   be mapped.
+ */
+export function remapColumnIdBlockIds<T extends string | ColumnUniversalKey>(
+  id: T,
+  remapBlockId: (blockId: string) => string,
+): T {
+  const remapped = isString(id) ? remapIdString(id, remapBlockId) : remapKey(id, remapBlockId);
+  return (remapped ?? id) as T;
+}
+
+/**
+ * The string half of {@link remapColumnIdBlockIds}. `undefined` means "nothing to change",
+ * which is what keeps an unaffected id from being re-serialized.
+ *
+ * Escape padding is peeled and put back, so an id that reached params through an extra
+ * `JSON.stringify` is rewritten in place and comes back wrapped as it was found. A string
+ * that does not peel to a column key is left alone: params hold ordinary strings too.
+ */
+function remapIdString(id: string, remapBlockId: (blockId: string) => string): string | undefined {
+  const peeled = peelJsonLayers(id);
+  if (peeled === undefined || !isColumnUniversalKey(peeled.value)) return undefined;
+
+  const remappedKey = remapKey(peeled.value, remapBlockId);
+  if (remappedKey === undefined) return undefined;
+
+  let rebuilt: string = stringifyColumnId(remappedKey);
+  for (let layer = 0; layer < peeled.layers; layer++) rebuilt = JSON.stringify(rebuilt);
+  return rebuilt;
+}
+
+/** The key half of {@link remapColumnIdBlockIds}. `undefined` means "nothing to change". */
+function remapKey(
+  key: ColumnUniversalKey,
+  remapBlockId: (blockId: string) => string,
+): ColumnUniversalKey | undefined {
+  if (isGlobalPObjectKey(key)) {
+    const blockId = remapBlockId(key.blockId);
+    return blockId === key.blockId ? undefined : { ...key, blockId };
+  }
+
+  // A local leaf names its column by a path inside its own block — no block id.
+  if (isLocalPObjectKey(key)) return undefined;
+
+  if (isColumnFilteredKey(key)) {
+    const source = remapIdString(key.source, remapBlockId);
+    return source === undefined ? undefined : { ...key, source: source as ColumnUniversalId };
+  }
+
+  if (isColumnOverriddenKey(key)) {
+    const source = remapIdString(key.source, remapBlockId);
+    // Remapping preserves the id's shape, so `source` is still not an Overridden id.
+    return source === undefined
+      ? undefined
+      : { ...key, source: source as ColumnOverriddenKey["source"] };
+  }
+
+  if (isColumnDiscoveredKey(key)) return remapDiscoveredKey(key, remapBlockId);
+
+  throw new Error(
+    `remapColumnIdBlockIds: unrecognized column id structure: ${JSON.stringify(key)}`,
+  );
+}
+
+/**
+ * Discovered is the only key form carrying more than one nested id: the column it
+ * discovered, one per linker hop, and one per entry in `queriesQualifications` — where the
+ * id is the map key, not the value.
+ */
+function remapDiscoveredKey(
+  key: ColumnDiscoveredKey,
+  remapBlockId: (blockId: string) => string,
+): ColumnDiscoveredKey | undefined {
+  const column = remapIdString(key.column, remapBlockId);
+
+  let pathChanged = false;
+  const path = key.path?.map((item) => {
+    const itemColumn = remapIdString(item.column, remapBlockId);
+    if (itemColumn === undefined) return item;
+    pathChanged = true;
+    return { ...item, column: itemColumn as ColumnUniversalId };
+  });
+
+  let queriesChanged = false;
+  const queriesQualifications =
+    key.queriesQualifications &&
+    (Object.fromEntries(
+      Object.entries(key.queriesQualifications).map(([queryId, qualifications]) => {
+        const remappedId = remapIdString(queryId, remapBlockId);
+        if (remappedId === undefined) return [queryId, qualifications];
+        queriesChanged = true;
+        return [remappedId, qualifications];
+      }),
+    ) as ColumnDiscoveredKey["queriesQualifications"]);
+
+  if (column === undefined && !pathChanged && !queriesChanged) return undefined;
+  return {
+    ...key,
+    ...(column !== undefined ? { column: column as ColumnUniversalId } : {}),
+    ...(pathChanged ? { path } : {}),
+    ...(queriesChanged ? { queriesQualifications } : {}),
+  };
+}
+
 /**
  * Walk a rich column id down to its terminal leaf {@link PObjectId}.
  */

package/src/index.ts

@@ -23,3 +23,4 @@ export * from "./services";
 export * from "./pool_entry";
 export * from "./project_id";
 export * from "./columns";
+export * from "./template";

package/src/plid.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { base32Encode } from "./base32_encode";
+import { Branded } from "@milaboratories/helpers";
 
 /** Number of raw bytes in the PlId. */
 export const PlIdBytes = 15;
@@ -9,19 +10,18 @@ export const PlIdLength = 24; // = 15 bytes * 8 bits / 5 bits per char in base32
 export const PlId = z
   .string()
   .length(PlIdLength)
-  .regex(/[ABCDEFGHIJKLMNOPQRSTUVWXYZ234567]/) // RFC4648
-  .brand("PlId");
-export type PlId = z.infer<typeof PlId>;
+  .regex(/[ABCDEFGHIJKLMNOPQRSTUVWXYZ234567]/); // RFC4648
+export type PlId = Branded<z.infer<typeof PlId>, "PlId">;
 
 export function uniquePlId(): PlId {
   const data = new Uint8Array(PlIdBytes);
   crypto.getRandomValues(data);
-  return PlId.parse(base32Encode(data, "RFC4648"));
+  return PlId.parse(base32Encode(data, "RFC4648")) as PlId;
 }
 
 export function plId(bytes: Uint8Array): PlId {
   if (bytes.length !== PlIdBytes) throw new Error(`Wrong number of bytes: ${bytes.length}`);
-  return PlId.parse(base32Encode(bytes, "RFC4648"));
+  return PlId.parse(base32Encode(bytes, "RFC4648")) as PlId;
 }
 
 export async function digestPlId(data: string): Promise<PlId> {

package/src/template/index.ts

@@ -0,0 +1,4 @@
+export * from "./kind_selector";
+export * from "./project_template_v1";
+export * from "./template_ref_form";
+export * from "./template_relocate";

package/src/template/kind_selector.ts

@@ -0,0 +1,126 @@
+import type { Branded } from "@milaboratories/helpers";
+import type { BlockKindReference } from "../bmodel/block_kind_ref";
+import { parseKindRef, splitVersionedName } from "../bmodel/block_kind_ref";
+
+/**
+ * Version-selection tier of a template entry's `kind` field.
+ *
+ * - `exact` — `X.Y.Z`: this version and no other.
+ * - `patch` — `~X.Y.Z`: patch floor, behavior frozen.
+ * - `minor` — `^X.Y.Z`: minor floor, behavior floats.
+ */
+export type KindSelectorOp = "exact" | "patch" | "minor";
+
+/** The version half of a `{name}@{selector}` kind reference, split into parts. */
+export type KindSelector = {
+  readonly op: KindSelectorOp;
+  readonly version: string;
+};
+
+/**
+ * On-wire reference to a *set* of block kind versions: `{name}@{selector}`, e.g.
+ * `@platforma-open/milaboratories.mixcr-clonotyping.kind@~1.2.0`.
+ *
+ * The template-file form of a kind reference, and the only form the
+ * `template-v1` schema accepts in an entry's `kind` field. It is the same string
+ * shape as {@link BlockKindReference} widened by the `~`/`^` tiers, but branded
+ * separately so a *resolved* kind reference is never silently passed where a
+ * selector is expected, or vice versa. Widen an exact reference explicitly with
+ * {@link kindReferenceToSelectorReference}.
+ */
+export type BlockKindSelectorReference = Branded<string, "BlockKindSelectorReference">;
+
+/** `X.Y.Z` with optional semver prerelease and build metadata. */
+const semVerRegex =
+  /^\d+\.\d+\.\d+(?:-[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?(?:\+[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?$/;
+
+/**
+ * Split a raw selector string (`1.2.0`, `~1.2.0`, `^1.2.0`) into its parts.
+ *
+ * The version is validated as `X.Y.Z`, so a range that is legal npm but not part
+ * of the kind grammar (`>=1.0.0`, `1.x`, `latest`) is rejected here rather than
+ * reaching resolution. Note the deliberate divergence from
+ * `tools/block-tools`'s `parseSelector`, which additionally tolerates a leading
+ * `@` as `exact`: after the `{name}@{selector}` split a leading `@` can only
+ * come from a doubled separator, which is malformed.
+ *
+ * Mapping a selector onto a concrete version is resolution, not parsing, and
+ * lives with the resolver (`kind_resolver.selectorToRange`).
+ *
+ * @throws if the version part is not `X.Y.Z`
+ */
+export function parseKindSelector(raw: string): KindSelector {
+  const s = raw.trim();
+  const op: KindSelectorOp = s.startsWith("~") ? "patch" : s.startsWith("^") ? "minor" : "exact";
+  const version = op === "exact" ? s : s.slice(1);
+  if (!semVerRegex.test(version)) {
+    throw new Error(
+      `Malformed kind version selector (expected 'X.Y.Z', '~X.Y.Z' or '^X.Y.Z'): ${raw}`,
+    );
+  }
+  return { op, version };
+}
+
+/** Render a {@link KindSelector} back to its on-wire string. */
+export function formatKindSelector(sel: KindSelector): string {
+  switch (sel.op) {
+    case "exact":
+      return sel.version;
+    case "patch":
+      return `~${sel.version}`;
+    case "minor":
+      return `^${sel.version}`;
+  }
+}
+
+/**
+ * Split a {@link BlockKindSelectorReference} into `{ name, selector }`.
+ *
+ * @throws if the reference carries no version segment, or the selector is
+ *   outside the `X.Y.Z` / `~X.Y.Z` / `^X.Y.Z` grammar
+ */
+export function parseKindSelectorReference(ref: BlockKindSelectorReference): {
+  name: string;
+  selector: KindSelector;
+} {
+  const { name, version } = splitVersionedName(ref, "kind selector reference", "{name}@{selector}");
+  return { name, selector: parseKindSelector(version) };
+}
+
+/**
+ * Compose a {@link BlockKindSelectorReference} from a name and selector.
+ *
+ * A formatter, not a validator — pass a selector that came from
+ * {@link parseKindSelector} or that you constructed from a known-good version.
+ */
+export function formatKindSelectorReference(k: {
+  name: string;
+  selector: KindSelector;
+}): BlockKindSelectorReference {
+  return `${k.name}@${formatKindSelector(k.selector)}` as BlockKindSelectorReference;
+}
+
+/**
+ * Widen a resolved {@link BlockKindReference} to its `exact`-tier selector form.
+ *
+ * The export direction: a block implements exactly one kind version, so export
+ * always emits `{name}@X.Y.Z`. Validates on the way through, so a
+ * malformed stored reference fails at the boundary rather than in the file.
+ */
+export function kindReferenceToSelectorReference(
+  ref: BlockKindReference,
+): BlockKindSelectorReference {
+  const { name, version } = parseKindRef(ref);
+  return formatKindSelectorReference({ name, selector: parseKindSelector(version) });
+}
+
+/** Whether `value` is a well-formed `{name}@{selector}` string. */
+export function isBlockKindSelectorReference(value: unknown): value is BlockKindSelectorReference {
+  if (typeof value !== "string") return false;
+  try {
+    parseKindSelectorReference(value as BlockKindSelectorReference);
+    return true;
+  } catch {
+    return false;
+  }
+}