@protobase/workflows 0.0.0-stage → 0.68.0

package/dist/definition/names.js

@@ -0,0 +1,14 @@
+//#region src/definition/names.ts
+/** Variables a definition cannot assign: `$states`, which the runner gives each expression. */
+const reservedVariables = /* @__PURE__ */ new Set(["states"]);
+/**
+* What an expression may read of `$states.context`, as name paths: the run's input and start time, and a secret by its
+* name (`Secrets.<NAME>`, the name required).
+*/
+const contextReads = [
+	["Execution", "Input"],
+	["Execution", "StartTime"],
+	["Secrets"]
+];
+//#endregion
+export { contextReads, reservedVariables };

package/dist/definition/problem.d.ts

@@ -0,0 +1,13 @@
+//#region src/definition/problem.d.ts
+/**
+ * Why a definition cannot be saved. `state` is the state's path: its name, or names joined by `/` inside a Map's item
+ * processor or a Parallel's branch (`Each/Fetch`, `Both/1/Mail`); `field` is the field within it, such as `Retry[0].IntervalSeconds`.
+ */
+export type Problem = {
+  state?: string;
+  field?: string;
+  message: string;
+};
+/** A problem as one line: `State "Fetch", field "Arguments.url": ...`. */
+export declare const problemText: ({ state, field, message }: Problem) => string;
+//#endregion

package/dist/definition/problem.js

@@ -0,0 +1,11 @@
+//#region src/definition/problem.ts
+/** A problem as one line: `State "Fetch", field "Arguments.url": ...`. */
+const problemText = ({ state, field, message }) => {
+	const where = [state !== void 0 && `state "${state}"`, field !== void 0 && `field "${field}"`].filter(Boolean).join(", ");
+	if (!where) return message;
+	return `${where.charAt(0).toUpperCase()}${where.slice(1)}: ${message}`;
+};
+/** A field path as `Retry[0].IntervalSeconds`. */
+const fieldPath = (parts) => parts.reduce((path, part) => typeof part === "number" || /^\d+$/.test(part) ? `${path}[${part}]` : path ? `${path}.${part}` : part, "");
+//#endregion
+export { fieldPath, problemText };

package/dist/definition/reads.js

@@ -0,0 +1,81 @@
+//#region src/definition/reads.ts
+const isNode = (value) => typeof value === "object" && value !== null && typeof value.type === "string";
+const relativeKeys = /* @__PURE__ */ new Set([
+	"stages",
+	"predicate",
+	"group",
+	"terms"
+]);
+const inputReads = /* @__PURE__ */ new Set([
+	"name",
+	"wildcard",
+	"descendant",
+	"parent"
+]);
+/** JSONata's own functions, which an expression calls as `$sum(...)`: no reads of a variable. */
+const builtInFunctions = new Set("sum count max min average string substring substringBefore substringAfter lowercase uppercase length trim pad match contains replace split join formatNumber formatBase formatInteger parseInteger number floor ceil round abs sqrt power random boolean not map zip filter single reduce sift keys lookup append exists spread merge reverse each error assert type sort shuffle distinct base64encode base64decode encodeUrlComponent encodeUrl decodeUrlComponent decodeUrl eval toMillis fromMillis clone now millis".split(" "));
+const opensScope = (value) => isNode(value) && (value.type === "block" || value.type === "lambda");
+const boundIn = (value, names = /* @__PURE__ */ new Set(), root = true) => {
+	if (Array.isArray(value)) {
+		for (const item of value) boundIn(item, names, false);
+		return names;
+	}
+	if (!isNode(value) || !root && opensScope(value)) return names;
+	if (value.type === "bind" && isNode(value.lhs) && value.lhs.type === "variable") names.add(String(value.lhs.value));
+	for (const [key, child] of Object.entries(value)) if (key !== "position" && key !== "value" && key !== "type") boundIn(child, names, false);
+	return names;
+};
+/** The reads of a compiled expression, from its syntax tree, each name read where it is bound counted as no read. */
+const expressionReads = (expression) => {
+	const variables = /* @__PURE__ */ new Set();
+	const states = [];
+	let input = false;
+	const inPath = /* @__PURE__ */ new WeakSet();
+	const visit = (value, rooted, outer) => {
+		if (Array.isArray(value)) return value.forEach((item) => visit(item, rooted, outer));
+		if (!isNode(value)) return;
+		let bound = outer;
+		if (opensScope(value)) {
+			const parameters = value.type === "lambda" && Array.isArray(value.arguments) ? value.arguments.map((argument) => String(argument.value)) : [];
+			bound = /* @__PURE__ */ new Set([
+				...outer,
+				...parameters,
+				...boundIn(value)
+			]);
+		}
+		if (value.type === "variable") {
+			const name = String(value.value);
+			if (name === "" || name === "$") input ||= rooted;
+			else if (!bound.has(name)) variables.add(name);
+		}
+		if (inputReads.has(value.type) && rooted) input = true;
+		if (value.type === "path" && Array.isArray(value.steps)) {
+			const [first] = value.steps;
+			if (first?.type === "variable" && first.value === "states") {
+				inPath.add(first);
+				const rest = value.steps.slice(1);
+				const end = rest.findIndex((step) => step.type !== "name" || step.stages !== void 0 || step.predicate !== void 0);
+				states.push(rest.slice(0, end === -1 ? rest.length : end + (rest[end]?.type === "name" ? 1 : 0)).map((step) => String(step.value)));
+			}
+			value.steps.forEach((step, index) => visit(step, index === 0 ? rooted : false, bound));
+		} else if (value.type === "variable" && value.value === "states" && !inPath.has(value)) states.push([]);
+		for (const [key, child] of Object.entries(value)) {
+			if (key === "steps" && value.type === "path") continue;
+			if (key === "position" || key === "value" || key === "type") continue;
+			visit(child, relativeKeys.has(key) || value.type === "filter" || value.type === "sort" ? false : rooted, bound);
+		}
+	};
+	const ast = expression.ast();
+	visit(ast, true, boundIn(ast));
+	const evaluates = variables.has("eval");
+	for (const name of builtInFunctions) variables.delete(name);
+	variables.delete("states");
+	return {
+		variables,
+		states,
+		input,
+		evaluates
+	};
+};
+//#endregion
+export { builtInFunctions, expressionReads };

package/dist/definition/schema.d.ts

@@ -0,0 +1,259 @@
+//#region src/definition/schema.d.ts
+/**
+ * The JSON Schema of a workflow definition: its trigger, and a state machine in the States Language with JSONata
+ * expressions, in the named-reads profile. It checks the shape; `checkDefinition` also checks the edges and what each expression reads.
+ */
+export declare const definitionSchema: {
+  readonly $schema: "http://json-schema.org/draft-07/schema#";
+  readonly $id: "https://docs.protobase.net/schemas/workflow-definition.json";
+  readonly $ref: "#/definitions/definition";
+  readonly definitions: {
+    readonly machine: {
+      readonly type: "object";
+      readonly required: readonly ["StartAt", "States"];
+      readonly properties: {
+        readonly StartAt: {
+          type: string;
+          minLength: number;
+          maxLength: number;
+        };
+        readonly Comment: {
+          readonly type: "string";
+        };
+        readonly States: {
+          readonly type: "object";
+          readonly minProperties: 1;
+          readonly propertyNames: {
+            type: string;
+            minLength: number;
+            maxLength: number;
+          };
+          readonly additionalProperties: {
+            readonly $ref: "#/definitions/state";
+          };
+        };
+      };
+    };
+    readonly definition: {
+      readonly type: "object";
+      readonly additionalProperties: false;
+      readonly required: readonly ["trigger", "stateMachine"];
+      readonly properties: {
+        readonly trigger: {
+          readonly $ref: "#/definitions/trigger";
+        };
+        readonly stateMachine: {
+          readonly $ref: "#/definitions/stateMachine";
+        };
+      };
+    };
+    readonly trigger: {
+      readonly type: "object";
+      readonly minProperties: 1;
+      readonly maxProperties: 1;
+      readonly propertyNames: {
+        readonly pattern: "^(manual|[a-z][a-z0-9_]*:[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*)$";
+      };
+      readonly properties: {
+        readonly manual: {
+          readonly type: "object";
+          readonly maxProperties: 0;
+        };
+      };
+      readonly additionalProperties: {
+        readonly type: "object";
+      };
+    };
+    readonly stateMachine: {
+      readonly allOf: readonly [{
+        readonly $ref: "#/definitions/machine";
+      }];
+      readonly required: readonly ["QueryLanguage"];
+      readonly properties: {
+        readonly QueryLanguage: {
+          readonly const: "JSONata";
+        };
+        readonly StartAt: {};
+        readonly States: {};
+        readonly Comment: {};
+      };
+      readonly additionalProperties: false;
+    };
+    readonly processor: {
+      readonly allOf: readonly [{
+        readonly $ref: "#/definitions/machine";
+      }];
+      readonly properties: {
+        readonly ProcessorConfig: {
+          readonly type: "object";
+          readonly additionalProperties: false;
+          readonly properties: {
+            readonly Mode: {
+              readonly const: "INLINE";
+            };
+          };
+        };
+        readonly StartAt: {};
+        readonly States: {};
+        readonly Comment: {};
+      };
+      readonly additionalProperties: false;
+    };
+    readonly state: {
+      readonly type: "object";
+      readonly required: readonly ["Type"];
+      readonly discriminator: {
+        readonly propertyName: "Type";
+      };
+      readonly oneOf: readonly [{
+        properties: {
+          Type: {
+            const: string;
+          };
+          Comment: {
+            type: string;
+          };
+          Output: {};
+          Assign: {
+            type: string;
+            propertyNames: {
+              pattern: string;
+            };
+          };
+          QueryLanguage: {
+            const: string;
+          };
+        };
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+      }, {
+        properties: {
+          Type: {
+            const: string;
+          };
+          Comment: {
+            type: string;
+          };
+          Output: {};
+          Assign: {
+            type: string;
+            propertyNames: {
+              pattern: string;
+            };
+          };
+          QueryLanguage: {
+            const: string;
+          };
+        };
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+      }, {
+        properties: {
+          Type: {
+            const: string;
+          };
+          Comment: {
+            type: string;
+          };
+          Output: {};
+          Assign: {
+            type: string;
+            propertyNames: {
+              pattern: string;
+            };
+          };
+          QueryLanguage: {
+            const: string;
+          };
+        };
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+      }, {
+        properties: {
+          Type: {
+            const: string;
+          };
+          Comment: {
+            type: string;
+          };
+          Output: {};
+          Assign: {
+            type: string;
+            propertyNames: {
+              pattern: string;
+            };
+          };
+          QueryLanguage: {
+            const: string;
+          };
+        };
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+      }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["Type"];
+        readonly properties: {
+          readonly Type: {
+            readonly const: "Succeed";
+          };
+          readonly Comment: {
+            readonly type: "string";
+          };
+          readonly Output: {};
+          readonly QueryLanguage: {
+            readonly const: "JSONata";
+          };
+        };
+      }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["Type"];
+        readonly properties: {
+          readonly Type: {
+            readonly const: "Fail";
+          };
+          readonly Comment: {
+            readonly type: "string";
+          };
+          readonly QueryLanguage: {
+            readonly const: "JSONata";
+          };
+          readonly Error: {
+            readonly type: "string";
+          };
+          readonly Cause: {
+            readonly type: "string";
+          };
+        };
+      }, {
+        properties: {
+          Type: {
+            const: string;
+          };
+          Comment: {
+            type: string;
+          };
+          Output: {};
+          Assign: {
+            type: string;
+            propertyNames: {
+              pattern: string;
+            };
+          };
+          QueryLanguage: {
+            const: string;
+          };
+        };
+        type: string;
+        additionalProperties: boolean;
+        required: string[];
+      }];
+    };
+  };
+};
+//#endregion

package/dist/definition/schema.js

@@ -0,0 +1,258 @@
+import { limits } from "../limits.js";
+//#region src/definition/schema.ts
+const expression = {
+	type: "string",
+	pattern: "^\\{%[\\s\\S]*%\\}$"
+};
+const name = {
+	type: "string",
+	minLength: 1,
+	maxLength: 80
+};
+const errorNames = {
+	type: "array",
+	minItems: 1,
+	items: {
+		type: "string",
+		minLength: 1
+	}
+};
+const assign = {
+	type: "object",
+	propertyNames: { pattern: "^[A-Za-z][A-Za-z0-9_]*$" }
+};
+const common = {
+	Type: {},
+	Comment: { type: "string" },
+	Output: {},
+	Assign: assign,
+	QueryLanguage: { const: "JSONata" }
+};
+const flow = {
+	Next: name,
+	End: { const: true }
+};
+const nextOrEnd = { oneOf: [{
+	required: ["Next"],
+	not: { required: ["End"] }
+}, {
+	required: ["End"],
+	not: { required: ["Next"] }
+}] };
+const recovery = {
+	Retry: {
+		type: "array",
+		items: {
+			type: "object",
+			additionalProperties: false,
+			required: ["ErrorEquals"],
+			properties: {
+				ErrorEquals: errorNames,
+				IntervalSeconds: {
+					type: "integer",
+					minimum: 1,
+					maximum: limits.retryDelaySeconds
+				},
+				MaxAttempts: {
+					type: "integer",
+					minimum: 0,
+					maximum: limits.retryAttempts
+				},
+				BackoffRate: {
+					type: "number",
+					minimum: 1,
+					maximum: 10
+				},
+				MaxDelaySeconds: {
+					type: "integer",
+					minimum: 1,
+					maximum: limits.retryDelaySeconds
+				}
+			}
+		}
+	},
+	Catch: {
+		type: "array",
+		items: {
+			type: "object",
+			additionalProperties: false,
+			required: ["ErrorEquals", "Next"],
+			properties: {
+				ErrorEquals: errorNames,
+				Next: name,
+				Output: {},
+				Assign: assign
+			}
+		}
+	}
+};
+const state = (type, properties, { required = [], ...extra } = {}) => ({
+	type: "object",
+	additionalProperties: false,
+	required: ["Type", ...required],
+	...extra,
+	properties: {
+		...common,
+		Type: { const: type },
+		...properties
+	}
+});
+/**
+* The JSON Schema of a workflow definition: its trigger, and a state machine in the States Language with JSONata
+* expressions, in the named-reads profile. It checks the shape; `checkDefinition` also checks the edges and what each expression reads.
+*/
+const definitionSchema = {
+	$schema: "http://json-schema.org/draft-07/schema#",
+	$id: "https://docs.protobase.net/schemas/workflow-definition.json",
+	$ref: "#/definitions/definition",
+	definitions: {
+		machine: {
+			type: "object",
+			required: ["StartAt", "States"],
+			properties: {
+				StartAt: name,
+				Comment: { type: "string" },
+				States: {
+					type: "object",
+					minProperties: 1,
+					propertyNames: name,
+					additionalProperties: { $ref: "#/definitions/state" }
+				}
+			}
+		},
+		definition: {
+			type: "object",
+			additionalProperties: false,
+			required: ["trigger", "stateMachine"],
+			properties: {
+				trigger: { $ref: "#/definitions/trigger" },
+				stateMachine: { $ref: "#/definitions/stateMachine" }
+			}
+		},
+		trigger: {
+			type: "object",
+			minProperties: 1,
+			maxProperties: 1,
+			propertyNames: { pattern: "^(manual|[a-z][a-z0-9_]*:[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*)$" },
+			properties: { manual: {
+				type: "object",
+				maxProperties: 0
+			} },
+			additionalProperties: { type: "object" }
+		},
+		stateMachine: {
+			allOf: [{ $ref: "#/definitions/machine" }],
+			required: ["QueryLanguage"],
+			properties: {
+				QueryLanguage: { const: "JSONata" },
+				StartAt: {},
+				States: {},
+				Comment: {}
+			},
+			additionalProperties: false
+		},
+		processor: {
+			allOf: [{ $ref: "#/definitions/machine" }],
+			properties: {
+				ProcessorConfig: {
+					type: "object",
+					additionalProperties: false,
+					properties: { Mode: { const: "INLINE" } }
+				},
+				StartAt: {},
+				States: {},
+				Comment: {}
+			},
+			additionalProperties: false
+		},
+		state: {
+			type: "object",
+			required: ["Type"],
+			discriminator: { propertyName: "Type" },
+			oneOf: [
+				state("Pass", flow, nextOrEnd),
+				state("Task", {
+					...flow,
+					...recovery,
+					Resource: name,
+					Arguments: {},
+					TimeoutSeconds: {
+						type: "integer",
+						minimum: 1,
+						maximum: limits.taskTimeoutSeconds
+					}
+				}, {
+					required: ["Resource"],
+					...nextOrEnd
+				}),
+				state("Choice", {
+					Choices: {
+						type: "array",
+						minItems: 1,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							required: ["Condition", "Next"],
+							properties: {
+								Condition: expression,
+								Next: name,
+								Comment: { type: "string" },
+								Output: {},
+								Assign: assign
+							}
+						}
+					},
+					Default: name
+				}, { required: ["Choices"] }),
+				state("Wait", {
+					...flow,
+					Seconds: { anyOf: [{
+						type: "integer",
+						minimum: 0,
+						maximum: limits.waitSeconds
+					}, expression] },
+					Timestamp: { type: "string" }
+				}, { allOf: [nextOrEnd, { oneOf: [{ required: ["Seconds"] }, { required: ["Timestamp"] }] }] }),
+				{
+					type: "object",
+					additionalProperties: false,
+					required: ["Type"],
+					properties: {
+						Type: { const: "Succeed" },
+						Comment: { type: "string" },
+						Output: {},
+						QueryLanguage: { const: "JSONata" }
+					}
+				},
+				{
+					type: "object",
+					additionalProperties: false,
+					required: ["Type"],
+					properties: {
+						Type: { const: "Fail" },
+						Comment: { type: "string" },
+						QueryLanguage: { const: "JSONata" },
+						Error: { type: "string" },
+						Cause: { type: "string" }
+					}
+				},
+				state("Map", {
+					...flow,
+					...recovery,
+					Items: {},
+					ItemProcessor: { $ref: "#/definitions/processor" },
+					MaxConcurrency: {
+						type: "integer",
+						minimum: 0,
+						maximum: limits.mapConcurrency
+					}
+				}, {
+					required: ["ItemProcessor", "Items"],
+					...nextOrEnd
+				})
+			]
+		}
+	}
+};
+//#endregion
+export { definitionSchema };