@toist/spec 0.7.1 → 0.8.1

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to `@toist/spec` are recorded here.
 
+## 0.8.1 — 2026-05-08
+
+Lockstep version bump. No functional changes in this package.
+
+## 0.8.0 — 2026-05-08
+
+- **Structural `DataHandle` / `DataStatement` interfaces** replace the
+  `bun:sqlite` `Database` import for `PlatformCtx.db`. Bun's real
+  `Database` structurally satisfies the interface; non-Bun runtimes can
+  supply their own implementation. Keeps `@toist/spec` source free of
+  Bun-specific imports.
+- `validateSpec(input, options)` accepts an optional `registry` for
+  scope-aware validation (used by `@toist/core`'s runner-aware wrapper).
+
 ## 0.7.1 — 2026-05-06
 
 Lockstep version bump. No functional changes in this package.

package/README.md

@@ -0,0 +1,54 @@
+# `@toist/spec`
+
+Pure Toist pipeline-format tooling: YAML parsing, discriminator/expression parsing, JSON Schema helpers, and offline validation.
+
+```ts
+import { parseYaml, validateSpec } from "@toist/spec"
+
+const spec = parseYaml(`
+apiVersion: "2121.fi/v1"
+id: hello
+nodes:
+  - id: greet
+    kind: data.json
+    params:
+      value: { message: "hello" }
+`)
+
+const result = validateSpec(spec)
+if (!result.ok) throw new Error(result.errors.join("; "))
+console.log(result.parsed?.id)
+```
+
+## What it exports
+
+- `parseYaml` / `YamlError`
+- `parseExpr`, `evalExpr`
+- `parseDisc`, `resolveDisc`
+- `validateSpec`
+- kind-contract types like `NodeKind`, `ExecContext`, `PlatformCtx`
+- JSON Schema helpers like `pipelineSchema` and `kindToNodeSchema`
+
+## Validation
+
+`validateSpec(input)` is pure. It checks pipeline shape, refs, cycles, payload schema, and returns parsed graph data:
+
+```ts
+const result = validateSpec(spec)
+if (result.ok) {
+  console.log(result.parsed?.parsedNodes)
+  console.log(result.parsed?.edges)
+}
+```
+
+If you have a live kind registry, pass kind resolvers through `ValidateOptions`.
+
+## Kind-facing types
+
+Kinds depend on the spec package for their contract:
+
+```ts
+import type { NodeKind } from "@toist/spec"
+```
+
+That keeps pipeline tooling and kind authoring free of runner/server dependencies.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toist/spec",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -9,7 +9,8 @@
   },
   "files": [
     "src/",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "README.md"
   ],
   "dependencies": {
     "@babel/parser": "^7.25.0",

package/src/index.ts

@@ -35,6 +35,8 @@ export {
   type SubRunOutcome,
   type OnErrorPolicy,
   type ErrorReviewSpec,
+  type DataHandle,
+  type DataStatement,
   type ParamDef,
   type PortDef,
   type Cache,

package/src/kinds.ts

@@ -10,7 +10,17 @@
 // the dependency graph. The split between this file and `validate.ts` is
 // for human clarity, not for bundle isolation.
 
-import type { Database } from "bun:sqlite"
+export interface DataStatement {
+  run(...args: unknown[]): unknown
+  get(...args: unknown[]): unknown
+  all(...args: unknown[]): unknown[]
+}
+
+export interface DataHandle {
+  exec(sql: string): unknown
+  prepare(sql: string): DataStatement
+  transaction(fn: (...args: any[]) => unknown): (...args: any[]) => unknown
+}
 
 export interface ParamDef {
   type: "string" | "number" | "boolean" | "expression" | "json" | "select"
@@ -121,7 +131,7 @@ export type SubRun = (pipelineId: string, payload: Record<string, unknown>) => P
 export interface PlatformCtx {
   runId: number
   log: (level: "info" | "warn" | "error", msg: string) => void
-  db: Database
+  db: DataHandle
   cache: Cache
   /** Resolved resource instances. ctx.resource.<name>.<field> in { expr } nodes. */
   resource: Record<string, Record<string, unknown>>