`dag.traverse`

Traverse ecosystem packages in dependency order, executing visit procedure for each

CLI

Package: @procedures/lib · README
Path: ["dag","traverse"]
CLI: mark dag traverse --visit <string[] | object>
As data: {"$proc":["dag","traverse"],"input":{}}
Tags: runs-refs

Use it

In TypeScript

import { Client, LocalTransport, PROCEDURE_REGISTRY } from "@procedures/client";
import "@procedures/lib"; // registers its procedures

const client = new Client(new LocalTransport({ registry: PROCEDURE_REGISTRY }));
const result = await client.exec(["dag","traverse"], { visit: "<visit>" });
console.log(JSON.stringify(result));

From the command line

$ mark dag traverse --visit <string[] | object>

As data, in a program

{ "$proc": ["dag", "traverse"], "input": { "visit": "<visit>" } }

Input

Field	Type	Required	Default	Description
`visit`	`string[] \| object`	yes		Procedure to execute for each node. - Array: procedure path, e.g., ["git", "add"] - $proc with $when: "$never" or "$parent": deferred, executed per-node Example: ```json { "$proc": ["git", "add"], "input": { "all": true }, "$when": "$parent" } ```
`filter`	`string[]`	no		Filter to specific package names
`root`	`string`	no		Start from specific root package
`rootPath`	`string`	no		Workspace root (defaults to the pnpm workspace that contains client-lib)
`concurrency`	`number`	no	`4`	Max parallel operations (default: 4)
`serialize`	`"auto" \| "repository" \| "none"`	no	`"auto"`	When the visits of nodes in one git repository run one at a time (default: "auto"). - "auto": when the visit calls a `git` procedure (git locks the index of the repository) - "repository": always - "none": never
`continueOnError`	`boolean`	no	`false`	Continue on error (default: false)
`dryRun`	`boolean`	no	`false`	Preview without executing (default: false)

Output

Field	Type	Required	Description
`success`	`boolean`	yes	True when every visit succeeded
`results`	`object[]`	yes	The result of each visited node
`totalDuration`	`number`	yes	The time of the traversal, in milliseconds
`visited`	`number`	yes	The number of visited nodes
`failed`	`number`	yes	The number of failed visits

JSON Schemas

{
  "input": {
    "type": "object",
    "properties": {
      "visit": {
        "anyOf": [
          {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          {
            "type": "object",
            "properties": {
              "$proc": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "input": {},
              "$when": {
                "type": "string"
              },
              "$name": {
                "type": "string"
              }
            },
            "required": [
              "$proc"
            ]
          }
        ],
        "description": "Procedure to execute for each node. - Array: procedure path, e.g., [\"git\", \"add\"] - $proc with $when: \"$never\" or \"$parent\": deferred, executed per-node Example: ```json { \"$proc\": [\"git\", \"add\"], \"input\": { \"all\": true }, \"$when\": \"$parent\" } ```"
      },
      "filter": {
        "description": "Filter to specific package names",
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "root": {
        "description": "Start from specific root package",
        "type": "string"
      },
      "rootPath": {
        "description": "Workspace root (defaults to the pnpm workspace that contains client-lib)",
        "type": "string"
      },
      "concurrency": {
        "default": 4,
        "description": "Max parallel operations (default: 4)",
        "type": "number"
      },
      "serialize": {
        "default": "auto",
        "description": "When the visits of nodes in one git repository run one at a time (default: \"auto\"). - \"auto\": when the visit calls a `git` procedure (git locks the index of the repository) - \"repository\": always - \"none\": never",
        "type": "string",
        "enum": [
          "auto",
          "repository",
          "none"
        ]
      },
      "continueOnError": {
        "default": false,
        "description": "Continue on error (default: false)",
        "type": "boolean"
      },
      "dryRun": {
        "default": false,
        "description": "Preview without executing (default: false)",
        "type": "boolean"
      }
    },
    "required": [
      "visit"
    ]
  },
  "output": {
    "type": "object",
    "properties": {
      "success": {
        "type": "boolean",
        "description": "True when every visit succeeded"
      },
      "results": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The package name of the node"
            },
            "path": {
              "type": "string",
              "description": "The folder of the node"
            },
            "success": {
              "type": "boolean",
              "description": "True when the visit succeeded"
            },
            "duration": {
              "type": "number",
              "description": "The time of the visit, in milliseconds"
            },
            "error": {
              "description": "The error of a failed visit",
              "type": "string"
            },
            "output": {
              "description": "The result of the visit"
            }
          },
          "required": [
            "name",
            "path",
            "success",
            "duration"
          ],
          "additionalProperties": {}
        },
        "description": "The result of each visited node"
      },
      "totalDuration": {
        "type": "number",
        "description": "The time of the traversal, in milliseconds"
      },
      "visited": {
        "type": "number",
        "description": "The number of visited nodes"
      },
      "failed": {
        "type": "number",
        "description": "The number of failed visits"
      }
    },
    "required": [
      "success",
      "results",
      "totalDuration",
      "visited",
      "failed"
    ],
    "additionalProperties": {}
  }
}