@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/dist/op.js

@@ -0,0 +1,188 @@
+/**
+ * Where a resource type keeps its brand. A symbol, so `defineConnector` tells a resource type
+ * (`defineResource`) from a group of operations; a registered one (`Symbol.for`), so a copy of
+ * this package reads what another copy made, as `VENDOR`.
+ */
+export const RESOURCE = Symbol.for("sanoma.resource");
+/**
+ * Where a connector keeps its vendor. A symbol, so it names no resource: `Object.values` and
+ * `keyof` over a connector see its resources only. A registered one (`Symbol.for`): a process
+ * may load two copies of this package (a connector's peer linked into a sanoma checkout, the
+ * app's from its tarball), and each must read the connectors the other made.
+ */
+export const VENDOR = Symbol.for("sanoma.vendor");
+/**
+ * The shape of a connector's `[VENDOR]` record. A process may load two builds of this package,
+ * and `resolveConfig` reads only a record of its own shape (`checkConnector`): change it with
+ * the record, so a build refuses a connector another build made in another shape.
+ */
+export const CONNECTOR_FORMAT = 1;
+/** One `<svg>` element, with nothing but whitespace around it. */
+const SVG_ELEMENT = /^\s*<svg[\s>][\s\S]*<\/svg>\s*$/;
+const isResourceGroup = (group) => (typeof group === "function" || typeof group === "object") &&
+    group !== null &&
+    group[RESOURCE] === true;
+/**
+ * Declares a vendor's operations, grouped by resource: `defineConnector("ghost", { post: { create: {...} } })`.
+ * A group may be a resource type from `defineResource`, under its own `type`, for its `read` and
+ * `import`: `defineConnector("github", { repository }, { package: "@sanoma-ai/connector-github" })`;
+ * it must be of the same vendor, and the connector needs `info.package`, whose `/resources`
+ * entry exports the types for data files.
+ * `info` says who the vendor is and where the connector lives, for a UI:
+ * `{ title: "Resend", logo: { svg }, package: "@sanoma-ai/connector-resend", homepage: "https://…" }`.
+ */
+export function defineConnector(vendor, specs, info) {
+    // A copy, frozen once checked: changing the caller's object later cannot slip a logo past the check.
+    const logo = info?.logo && Object.freeze(Object.fromEntries(Object.entries(info.logo).filter(([, v]) => v !== undefined)));
+    for (const [variant, svg] of Object.entries(logo ?? {})) {
+        if (typeof svg !== "string" || !SVG_ELEMENT.test(svg)) {
+            throw new Error(`defineConnector("${vendor}"): logo.${variant} must be inline SVG markup, one <svg>…</svg> element`);
+        }
+    }
+    const vendorInfo = info && Object.freeze({ ...info, ...(logo && { logo: logo }) });
+    // It becomes a link's href: a whole https URL, so never a `javascript:` one. Checked on the copy kept.
+    const homepage = vendorInfo?.homepage;
+    if (homepage !== undefined && (typeof homepage !== "string" || URL.parse(homepage)?.protocol !== "https:"))
+        throw new Error(`defineConnector("${vendor}"): homepage must be an https URL`);
+    const out = {};
+    const resources = [];
+    for (const [resource, group] of Object.entries(specs)) {
+        let ops = group;
+        if (isResourceGroup(group)) {
+            if (group.vendor !== vendor) {
+                throw new Error(`defineConnector("${vendor}"): ${resource} is a resource type of ${group.vendor}`);
+            }
+            if (group.type !== resource) {
+                throw new Error(`defineConnector("${vendor}"): the resource type ${group.type} is given as ${resource}`);
+            }
+            resources.push(group);
+            ops = group.ops;
+        }
+        out[resource] = {};
+        for (const [name, spec] of Object.entries(ops)) {
+            out[resource][name] = Object.freeze({
+                kind: "op",
+                id: `${vendor}.${resource}.${name}`,
+                vendor,
+                resource,
+                name,
+                effect: spec.effect,
+                idempotent: spec.idempotent ?? false,
+                description: spec.description,
+                target: spec.target,
+                phrases: spec.phrases,
+                ...(spec.opaque?.length ? { opaque: spec.opaque } : {}),
+                input: spec.input,
+                output: spec.output,
+            });
+        }
+    }
+    // A data file imports the resource types from `<package>/resources`, which the reader matches exactly.
+    if (resources.length && !vendorInfo?.package) {
+        throw new Error(`defineConnector("${vendor}"): a connector with resource types needs info.package, the npm package data files import them from (\`<package>/resources\`)`);
+    }
+    const owner = Object.freeze({
+        format: CONNECTOR_FORMAT,
+        id: vendor,
+        info: vendorInfo,
+        resources: Object.freeze(resources),
+    });
+    return { ...out, [VENDOR]: owner };
+}
+/**
+ * A vendor's answer that the driver understood. `retryable` tells the runtime whether to try
+ * again (an idempotent operation on a timeout or a 5xx) or to stop (a 4xx). `status` and
+ * `vendorCode` keep what the vendor said, so the ledger and the UI can show it.
+ */
+export class DriverError extends Error {
+    code = "driver_failed";
+    retryable;
+    status;
+    vendorCode;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "DriverError";
+        this.retryable = options.retryable;
+        if (options.status !== undefined)
+            this.status = options.status;
+        if (options.vendorCode !== undefined)
+            this.vendorCode = options.vendorCode;
+    }
+}
+/**
+ * Whether a vendor's HTTP status is worth retrying: a request timeout (408), a rate limit (429)
+ * or a server error (5xx). It is the runtime's default rule; a driver adds its vendor's
+ * exceptions around it, such as a quota that does not lift in the seconds a retry waits.
+ */
+export function retryableStatus(status) {
+    return status === 408 || status === 429 || status >= 500;
+}
+/**
+ * The connector with `setup` laid over what it already carries, as a connector package exports
+ * it: `export const ghost = withSetup(ghostOps, { driver: ghostDriver, fake: fakeGhost, steps: ghostSteps })`. A
+ * config that needs a driver made otherwise (another bridge, other options) swaps that one and
+ * keeps the fake: `withSetup(github, { driver: () => githubDriver({ bridge }) })`. The operations
+ * are the same objects, and the type is the connector's. The setup is kept on the connector's
+ * vendor record (`[VENDOR]`), so a spread copy of the connector keeps it.
+ */
+export function withSetup(connector, setup) {
+    const owner = connector[VENDOR];
+    return {
+        ...connector,
+        [VENDOR]: Object.freeze({ ...owner, setup: Object.freeze({ ...owner.setup, ...setup }) }),
+    };
+}
+/**
+ * Throws unless `value` is a connector this package can read: one `defineConnector` made, in this
+ * copy of the package or another of the same `CONNECTOR_FORMAT`. One an older build made (its
+ * `VENDOR` an unregistered symbol, or its record without a format) is refused as such.
+ */
+export function checkConnector(value) {
+    const record = typeof value === "object" && value !== null ? value[VENDOR] : undefined;
+    if (record?.format === CONNECTOR_FORMAT)
+        return;
+    const build = "install the sanoma packages and connectors from one build";
+    throw new Error(record === undefined
+        ? `\`connectors\` holds something that is not a connector: list what the connector packages export (or one from an older build: ${build})`
+        : `The "${String(record.id)}" connector was made by another build of @sanoma-ai/workflows: ${build}`);
+}
+/** What `withSetup` attached to a connector: nothing when it attached nothing. */
+export const setupOf = (connector) => connector[VENDOR].setup ?? {};
+export function isOp(x) {
+    return typeof x === "object" && x !== null && x.kind === "op";
+}
+/**
+ * Implements a connector's operations, typed by its schemas. A driver must be complete: an
+ * operation the connector declares that `impl` leaves out, or one `impl` adds that the
+ * connector doesn't declare, is refused here rather than when a run calls it. `options.env`
+ * declares the environment variables it reads (see `DriverEnv`).
+ */
+export function defineDriver(connector, impl, options = {}) {
+    const declared = new Map();
+    for (const resource of Object.values(connector)) {
+        for (const op of Object.values(resource))
+            if (isOp(op))
+                declared.set(`${op.resource}.${op.name}`, op);
+    }
+    const vendor = connector[VENDOR].id;
+    const ops = {};
+    const extra = [];
+    for (const [resource, fns] of Object.entries(impl)) {
+        for (const [name, fn] of Object.entries(fns ?? {})) {
+            const key = `${resource}.${name}`;
+            if (!declared.has(key))
+                extra.push(`${vendor}.${key}`);
+            else if (typeof fn === "function")
+                ops[key] = fn;
+        }
+    }
+    const missing = [...declared.keys()].filter((key) => !Object.hasOwn(ops, key)).map((key) => `${vendor}.${key}`);
+    const problems = [
+        ...(missing.length ? [`it does not implement ${missing.join(", ")}`] : []),
+        ...(extra.length ? [`it implements ${extra.join(", ")}, which the connector does not declare`] : []),
+    ];
+    if (problems.length)
+        throw new Error(`defineDriver("${vendor}"): ${problems.join("; ")}`);
+    return Object.freeze({ vendor, ops: Object.freeze(ops), ...(options.env && { env: options.env }) });
+}
+//# sourceMappingURL=op.js.map

package/dist/op.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"op.js","sourceRoot":"","sources":["../src/op.ts"],"names":[],"mappings":"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"}

package/dist/outline.d.ts

@@ -0,0 +1,179 @@
+import { type Node, type SourceFile } from "./ast.ts";
+import { type WorkflowDefinition } from "./define.ts";
+/**
+ * What a workflow's `run` calls through `ctx`, in the order it makes the calls, with the loops,
+ * branches, `try` blocks and `ctx.all` groups around them. Read from the file that defined the
+ * workflow, and a contract: `run` may write only what the outline can draw (`outlineBody`'s
+ * problems; the worker refuses a workflow with any, the lint reports them), and the worker
+ * places every `ctx` call a run makes at its node (`callAt`), refusing one made from code the
+ * outline has no node for (`call_not_in_outline`). Every record a call writes names its node
+ * (`node`), so a run's steps are the outline's calls and nothing else.
+ */
+export type Outline = 
+/** Read from the file that defined the workflow (`wf.file`): the spans index into its text. */
+{
+    nodes: OutlineNode[];
+    file: string;
+} | {
+    error: string;
+};
+/** Where a node is in the text the outline was read from: UTF-16 offsets, as a string index or CodeMirror counts them. */
+export type Span = readonly [start: number, end: number];
+/**
+ * Each node's `path` is its place in the outline: its index among its siblings, under its
+ * parent's path and the index of the branch, case or body it is in (`"2"`, `"2.1.0"`), so the
+ * same tree has the same paths however the code is laid out; a ledger record's `node` is one.
+ * Each node's `span` is the code it stands for: the call for `op`, `approval` and `sleep`, the
+ * `ctx.all(...)` call for `all` and `each`, the loop or the iterating call (`items.map(cb)`) for
+ * `repeat`, the whole `if` / `else if` chain, `switch`, `?:` or `&&` for `branch`, and the `try`
+ * statement for `try`.
+ *
+ * A call's `name` is its step's name, what a test and the graph call it: the one the call gives
+ * (`{ name: "…" }`, on `op` and `sleep`), else its operation's id, or `Sleep`
+ * (`DEFAULT_SLEEP_NAME`); an approval's is its `title`. A computed call without a name of its
+ * own has none here: the operation it calls, known only in a run, names it. A name given, and an
+ * approval's title, is one step's only; an unnamed call's may be several's. A loop's `label`
+ * (`repeat`, and `each`) is read from its code, "for each of subscribers" for
+ * `for (const s of subscribers)` or `subscribers.map(…)`, "repeat while queue.length" for a
+ * `while`: no step's name.
+ */
+export type OutlineNode = {
+    path: string;
+    span: Span;
+} & 
+/**
+ * `ctx.<vendor>.<resource>.<name>(...)`, a computed segment shown as `*`. An id with one has
+ * `ops`: the ids in the workflow's `uses` it fits (`fitsOp`), sorted, which is what the call
+ * can reach; an id with every segment literal has none.
+ */
+/** `name`: the one the call gives (`ctx.x.y.z(input, { name: "…" })`), else the id when no segment is computed. */
+({
+    kind: "op";
+    id: string;
+    ops?: string[];
+    name?: string;
+}
+/**
+ * `ctx.approval(...)`, with its title, and the title as its `name`, when the first argument is
+ * a string literal or a top-level `const` holding one.
+ */
+ | {
+    kind: "approval";
+    title?: string;
+    name?: string;
+}
+/** `name`: the one the call gives (`ctx.sleep(request, { name: "…" })`), else `DEFAULT_SLEEP_NAME`. */
+ | {
+    kind: "sleep";
+    name: string;
+}
+/** `ctx.all([...])` over an array literal: one branch per element. */
+ | {
+    kind: "all";
+    branches: OutlineNode[][];
+}
+/** `ctx.all(items.map(cb))`: what the callback's member does, labelled from the code (`for each of items`). */
+ | {
+    kind: "each";
+    label: string;
+    body: OutlineNode[];
+}
+/**
+ * A loop, or a `.map` / `.forEach` / `.reduce` callback, whose body makes ctx calls, labelled
+ * from the code: `for each of items`, `for each key of record`, `repeat while cond`, `repeat`.
+ */
+ | {
+    kind: "repeat";
+    label: string;
+    body: OutlineNode[];
+}
+/**
+ * `if`, `switch`, `?:`, `&&`, `||` or `??`: one case per arm that makes ctx calls, and one empty
+ * case for the way past them when there is one (an arm without calls, an `if` without `else`,
+ * a `switch` without `default`, the right side of `&&` not run).
+ */
+ | {
+    kind: "branch";
+    cases: OutlineNode[][];
+}
+/** `try { body } catch { handler }`: the handler runs when the body fails. A `finally` makes no calls. */
+ | {
+    kind: "try";
+    body: OutlineNode[];
+    handler: OutlineNode[];
+});
+/** The node kinds a `ctx` call is: what a call site resolves to (`callAt`). */
+export type CallNode = Extract<OutlineNode, {
+    kind: "op" | "approval" | "sleep" | "all" | "each";
+}>;
+/** Something in `run` the outline cannot draw, at an offset into the file, and what to write instead. */
+export interface OutlineProblem {
+    start: number;
+    message: string;
+}
+/**
+ * Outlines a workflow from the file that defined it (`wf.file`): TypeScript or, once built,
+ * JavaScript. Counts only calls on `run`'s first parameter, whatever it is named. Returns
+ * `{ error }` when the file cannot be read or parsed, holds no workflow of that name, `run`
+ * takes no `ctx` by name, or `run` holds what the outline cannot draw (each problem at
+ * `file:line:column`).
+ */
+export declare const outlineWorkflow: (wf: WorkflowDefinition<any, any>) => Outline;
+/**
+ * `outlineWorkflow` over `file`, the workflow's file as `readSource` read it, with the text its
+ * spans index into (none with an `{ error }`). `found` is whether the file was parsed and holds
+ * the workflow's `run`: an `{ error }` with it found is what `run` holds that the outline cannot
+ * draw, which the lint reports too; one without is the file's (unread, unparsed, or no workflow
+ * of that name).
+ */
+export declare function outlineWithSource(wf: WorkflowDefinition<any, any>, file: SourceFile | string): {
+    outline: Outline;
+    source?: string;
+    found: boolean;
+};
+/** The file's top-level string constants, `export const NAME = "drift"`, by name: what a name may be besides a literal. */
+export declare function constsOf(program: Node): ReadonlyMap<string, string>;
+/**
+ * The nodes of `fn`'s body (`run`'s, or a callback's the outline reads), each with an empty `path`
+ * for `withPaths` to fill, and the problems: what the body does that the graph could not show.
+ * A call's `{ name }`, and an approval's title, is a string literal or one of `consts`
+ * (`constsOf` the file); a name given is not an operation's id or `Sleep`, and no two steps are
+ * given one name (`twiceNamed`). A loop's label quotes its code from `source`, the file's text.
+ * `ctx` is `fn`'s first parameter, taken by one name (destructured is a problem; none, and the
+ * body makes no calls). `ctx` is only called, directly, as an operation or a built-in, or read
+ * for `ctx.runId`; a function defined inside that uses `ctx` is read only where the outline
+ * reads callbacks (`ctx.all`'s members, `.map`, `.forEach` and `.reduce`), elsewhere it is a
+ * problem; a `finally` may not use `ctx`; and in a body the outline reads, `return` comes last,
+ * `throw` only in a `catch`, `break` leaves only a `switch`, and there is no `continue`. A
+ * callback without `ctx` computes, and is not read.
+ */
+export declare function outlineBody(fn: Node, { consts, source }: {
+    consts: ReadonlyMap<string, string>;
+    source: string;
+}): {
+    nodes: OutlineNode[];
+    problems: OutlineProblem[];
+};
+/** The outline's call nodes, wherever they are in it, in order: what `callAt` searches. */
+export declare const callsOf: (nodes: readonly OutlineNode[]) => CallNode[];
+/** What a call node is called as on `ctx`: the operation's id (`*` for a computed segment), or `all`, `approval`, `sleep`. */
+export declare const callName: (node: CallNode) => string;
+/**
+ * The call a position in the source belongs to: the innermost of `calls` (`callsOf`) whose span
+ * holds the offset, as a stack frame places a call at its callee (`ctx.ghost.post.create(…)` at
+ * `create`). A call inside another's arguments is the inner one. None when no call's code holds
+ * it: a call made from a helper, or from a function defined inside `run`, which the outline does
+ * not read.
+ */
+export declare function callAt(calls: readonly CallNode[], offset: number): CallNode | undefined;
+/** The node under the wrappers that leave its value as it is, and a default's pattern. */
+export declare function unwrap(node: Node): Node;
+/**
+ * Every workflow literal in a parsed file: the object literal `defineWorkflow({ name, …, run })`
+ * (or `sanoma.defineWorkflow(…)`) is called with, when it has a `name` and a `run` function. For
+ * the outline, which picks the one by its name, and the lint, which checks each `run`.
+ */
+export declare function workflowLiterals(program: Node): {
+    name: Node;
+    run: Node;
+}[];