fascicle 0.16.3 → 0.16.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -308,7 +308,10 @@ const COLUMN_GAP = 2;
308
308
  */
309
309
  function render_diagram(root, options) {
310
310
  const rows = [];
311
- flatten(to_item(root, void 0, options?.replays === true ? replay_gates(root) : /* @__PURE__ */ new Map()), "", "", rows);
311
+ flatten(to_item(root, void 0, {
312
+ marks: options?.replays === true ? replay_gates(root) : /* @__PURE__ */ new Map(),
313
+ internals: options?.internals === true
314
+ }), "", "", rows);
312
315
  const column = Math.max(...rows.map((row) => row.lead.length + row.head.length)) + COLUMN_GAP;
313
316
  const prefix = options?.prefix ?? "";
314
317
  const limit = options?.width === void 0 ? Number.POSITIVE_INFINITY : options.width - prefix.length - column;
@@ -358,12 +361,12 @@ function wrap(words, limit) {
358
361
  * Convert one node into the item the layout draws. `role` is the name the
359
362
  * parent gives this child, and it is dropped when it only repeats the label.
360
363
  */
361
- function to_item(node, role, marks) {
364
+ function to_item(node, role, draw) {
362
365
  const { label, by_kind } = label_of(node);
363
366
  return {
364
367
  head: role === void 0 || role === label ? label : `${role} ${label}`,
365
- note: [...note_of(node, by_kind), ...replay_note(marks.get(node))],
366
- children: child_items(node, marks)
368
+ note: [...note_of(node, by_kind), ...replay_note(draw.marks.get(node))],
369
+ children: child_items(node, draw)
367
370
  };
368
371
  }
369
372
  /**
@@ -391,16 +394,58 @@ function note_of(node, by_kind) {
391
394
  * Convert a node's children, naming each by the role its parent's kind gives
392
395
  * it.
393
396
  */
394
- function child_items(node, marks) {
397
+ function child_items(node, draw) {
395
398
  const children = node.children ?? [];
396
- if (node.kind === "branch") return children.map((child, i) => to_item(child, BRANCH_ROLES[i], marks));
397
- if (node.kind === "loop") return children.map((child, i) => to_item(child, i === 1 ? "guard" : void 0, marks));
399
+ const parts = draw.internals ? [] : part_nodes(node);
400
+ if (parts.length > 0) return parts.map(([role, part]) => to_item(part, role, draw));
401
+ if (node.kind === "branch") return children.map((child, i) => to_item(child, BRANCH_ROLES[i], draw));
402
+ if (node.kind === "loop") return children.map((child, i) => to_item(child, i === 1 ? "guard" : void 0, draw));
398
403
  if (node.kind === "parallel") {
399
404
  const keys = string_list(node.config?.["keys"]);
400
- return children.map((child, i) => to_item(child, keys[i], marks));
405
+ return children.map((child, i) => to_item(child, keys[i], draw));
401
406
  }
402
- if (node.kind === "chain") return staged_items(children, string_list(node.config?.["plan"]), marks);
403
- return children.map((child) => to_item(child, void 0, marks));
407
+ if (node.kind === "chain") return staged_items(children, string_list(node.config?.["plan"]), draw);
408
+ return children.map((child) => to_item(child, void 0, draw));
409
+ }
410
+ /**
411
+ * The parts that a named composite records, by role, each resolved to the
412
+ * node its path leads to. A composite that records none, or a path that leads
413
+ * nowhere (a hand-edited tree, say), reads as no parts, and the composite's
414
+ * own children are drawn instead.
415
+ */
416
+ function part_nodes(node) {
417
+ const parts = node.config?.["parts"];
418
+ if (node.kind !== "compose" || !is_flow_record(parts)) return [];
419
+ const resolved = [];
420
+ for (const [role, path] of Object.entries(parts)) {
421
+ const part = follow(node, path);
422
+ if (part === void 0) return [];
423
+ resolved.push([role, part]);
424
+ }
425
+ return resolved;
426
+ }
427
+ /**
428
+ * The node that a path of child indices leads to from `from`, or `undefined`
429
+ * when the path isn't a list of indices that each name a child.
430
+ */
431
+ function follow(from, path) {
432
+ if (!Array.isArray(path)) return void 0;
433
+ const steps = path;
434
+ let current = from;
435
+ for (const index of steps) {
436
+ if (typeof index !== "number") return void 0;
437
+ current = current?.children?.[index];
438
+ }
439
+ return current === from ? void 0 : current;
440
+ }
441
+ /**
442
+ * True for a config value that's a record rather than a list or a scalar. A
443
+ * marker such as a function's reads as a record too, and `follow` turns it
444
+ * away, since none of its values is a path.
445
+ */
446
+ function is_flow_record(value) {
447
+ if (value === null || Array.isArray(value)) return false;
448
+ return typeof value === "object";
404
449
  }
405
450
  /**
406
451
  * Convert a chain's children in plan order, nesting the entries after each
@@ -408,7 +453,7 @@ function child_items(node, marks) {
408
453
  * encloses them in the trajectory. Children the plan does not account for
409
454
  * follow in order, so a node without a plan still draws every child.
410
455
  */
411
- function staged_items(children, plan, marks) {
456
+ function staged_items(children, plan, draw) {
412
457
  const top = [];
413
458
  let target = top;
414
459
  let next = 0;
@@ -423,9 +468,9 @@ function staged_items(children, plan, marks) {
423
468
  } else {
424
469
  const child = children[next];
425
470
  next += 1;
426
- if (child !== void 0) target.push(to_item(child, void 0, marks));
471
+ if (child !== void 0) target.push(to_item(child, void 0, draw));
427
472
  }
428
- for (const child of children.slice(next)) target.push(to_item(child, void 0, marks));
473
+ for (const child of children.slice(next)) target.push(to_item(child, void 0, draw));
429
474
  return top;
430
475
  }
431
476
  /**
@@ -2330,8 +2375,9 @@ register_traced_kind("parallel");
2330
2375
  * branch: conditional routing.
2331
2376
  *
2332
2377
  * `branch({ when, then, otherwise })` evaluates `when(input)`; if truthy, runs
2333
- * `then`, else runs `otherwise`. Both branches must return the same output
2334
- * type.
2378
+ * `then`, else runs `otherwise`. The branch returns whichever arm ran, so its
2379
+ * output type is the union of the two arms' outputs, and naming one output
2380
+ * type, as in `branch<Pair, number | null>`, holds both arms to it.
2335
2381
  */
2336
2382
  let branch_counter = 0;
2337
2383
  /**
@@ -2352,7 +2398,7 @@ function branch(config) {
2352
2398
  const id = next_id$8();
2353
2399
  const { when, then: then_step, otherwise: otherwise_step, name } = config;
2354
2400
  const run_fn = async (input, ctx) => {
2355
- return dispatch_step(await when(input) ? then_step : otherwise_step, input, ctx);
2401
+ return await when(input) ? dispatch_step(then_step, input, ctx) : dispatch_step(otherwise_step, input, ctx);
2356
2402
  };
2357
2403
  const config_meta = {
2358
2404
  when,
@@ -3050,21 +3096,61 @@ function next_id$1() {
3050
3096
  * The step's `kind` is always `'compose'`; `config.name` becomes the
3051
3097
  * `display_name` used as the span label. Throws a `TypeError` when `name`
3052
3098
  * is not a non-empty string, catching the mistake at construction time.
3099
+ *
3100
+ * Each of `config.parts` is recorded as the path of child indices that leads
3101
+ * to it from the composite, so `describe.json` keeps the whole tree that the
3102
+ * viewer maps spans onto while `describe.diagram` can draw just the parts. A
3103
+ * part that isn't inside `inner` throws, since there would be no path to draw.
3053
3104
  */
3054
3105
  function compose(inner, config) {
3055
3106
  const name = config?.name;
3056
3107
  if (typeof name !== "string" || name.length === 0) throw new TypeError("compose(inner, { name }): name must be a non-empty string");
3108
+ const parts = part_paths(inner, config.parts);
3057
3109
  const id = next_id$1();
3058
3110
  const run_fn = (input, ctx) => dispatch_step(inner, input, ctx);
3059
3111
  return {
3060
3112
  id,
3061
3113
  kind: "compose",
3062
3114
  children: [inner],
3063
- config: { display_name: name },
3115
+ config: parts === void 0 ? { display_name: name } : {
3116
+ display_name: name,
3117
+ parts
3118
+ },
3064
3119
  ...description_meta(config.description),
3065
3120
  run: run_fn
3066
3121
  };
3067
3122
  }
3123
+ /**
3124
+ * The path of child indices from the composite to each part, by role, or
3125
+ * `undefined` when there are no parts. Every path starts at `inner`, the
3126
+ * composite's only child.
3127
+ */
3128
+ function part_paths(inner, parts) {
3129
+ if (parts === void 0) return void 0;
3130
+ const paths = {};
3131
+ for (const [role, part] of Object.entries(parts)) {
3132
+ const path = path_to(inner, part, /* @__PURE__ */ new Set());
3133
+ if (path === void 0) throw new TypeError(`compose(inner, { parts }): part "${role}" (${part.kind} ${part.id}) is not inside inner, so the diagram would have nothing to draw for it`);
3134
+ paths[role] = [0, ...path];
3135
+ }
3136
+ return paths;
3137
+ }
3138
+ /**
3139
+ * The child indices that lead from `from` to `target`, found depth first by
3140
+ * identity, or `undefined` when `target` isn't below it. `seen` keeps a shared
3141
+ * step from being walked twice.
3142
+ */
3143
+ function path_to(from, target, seen) {
3144
+ if (from === target) return [];
3145
+ if (seen.has(from)) return void 0;
3146
+ seen.add(from);
3147
+ const children = from.children;
3148
+ if (children === void 0) return void 0;
3149
+ for (const [index, child] of children.entries()) {
3150
+ const rest = path_to(child, target, seen);
3151
+ if (rest !== void 0) return [index, ...rest];
3152
+ }
3153
+ }
3068
3154
  register_traced_kind("compose");
3069
3155
  //#endregion
3070
3156
  //#region src/core/checkpoint.ts
@@ -3437,8 +3523,9 @@ register_traced_kind("use");
3437
3523
  * `chain<i>(input_name?)` opens a builder whose threaded value is a record of
3438
3524
  * named outputs rather than a single value. The input type must be stated,
3439
3525
  * either as the type argument or via `.input<t>()` on the freshly opened
3440
- * chain; an unannotated `chain()` defaults to `never` so the omission fails
3441
- * at the `run` call site instead of accepting anything. `.step(name, fn)`
3526
+ * chain. An unannotated `chain()` takes a branded type that nothing satisfies,
3527
+ * so the omission fails at the first field read or the `run` call site, with
3528
+ * the fix spelled out in the message, instead of accepting anything. `.step(name, fn)`
3442
3529
  * runs `fn` over the record and merges its output back in under `name`;
3443
3530
  * `.stage(name, project?)` concludes a phase: it opens a grouping span in
3444
3531
  * the trajectory and, when `project` is given, replaces the record with the
@@ -3597,9 +3684,9 @@ function make_chain(input_name, entries, bound) {
3597
3684
  /**
3598
3685
  * Open a chain builder whose record starts as `{ [input_name]: input }`.
3599
3686
  *
3600
- * `input_name` defaults to `'input'`. The input type defaults to `never`, so
3601
- * a chain that never states it produces a `Step<never, o>` that no real
3602
- * input satisfies at `run`; state it as the type argument or, when the
3687
+ * `input_name` defaults to `'input'`. The input type defaults to a branded
3688
+ * `ChainInputUndeclared` that no real input satisfies at `run`, and whose
3689
+ * name in an error says what to do; state it as the type argument or, when the
3603
3690
  * binding is renamed, once via `.input<t>()` on the fresh builder. Each
3604
3691
  * `.step` narrows subsequent callbacks to the record accumulated so far, and
3605
3692
  * `.stage` with a projection re-types the record to the projection's
@@ -3619,4 +3706,4 @@ register_traced_kind("chain");
3619
3706
  //#endregion
3620
3707
  export { describe_cycle_error as A, durable as C, describe as D, run as E, suspended_error as F, timeout_error as I, STEP_KINDS as L, flow_changed_error as M, resume_validation_error as N, is_step as O, run_not_found_error as P, is_step_kind as R, suggest_step_id as S, validate_schema as T, parallel as _, suspend as a, assert_valid_step_id as b, loop as c, retry as d, compute_backoff as f, branch as g, map as h, use as i, error_path as j, aborted_error as k, timeout as l, pipe as m, scope as n, checkpoint as o, wait_with_abort as p, stash as r, compose as s, chain as t, fallback as u, sequence as v, format_schema_issues as w, is_valid_step_id as x, step as y, resolve_display_name as z };
3621
3708
 
3622
- //# sourceMappingURL=core-CErsxGF6.js.map
3709
+ //# sourceMappingURL=core-BOFcG3tp.js.map