@db-lyon/flowkit 0.11.1 → 0.12.0

package/docs/getting-started.md

@@ -0,0 +1,172 @@
+# Getting started
+
+This guide walks through setting up flowkit from scratch.
+
+## Prerequisites
+
+- Node.js >= 20
+- TypeScript project with `"module": "NodeNext"` (or compatible ESM setup)
+
+## Install
+
+```bash
+npm install @db-lyon/flowkit
+```
+
+## 1. Create a YAML config
+
+Create `config/pipeline.yml`:
+
+```yaml
+tasks:
+  greet:
+    class_path: tasks.Greet
+    description: Print a greeting
+    options:
+      name: world
+
+flows:
+  hello:
+    description: Run the greeting
+    steps:
+      1:
+        task: greet
+```
+
+### What's happening here
+
+- **tasks** defines reusable units of work. Each task has a `class_path` that tells flowkit how to find the task implementation, and optional default `options`.
+- **flows** defines sequences of steps. Each step references a task (or another flow) by name. Steps execute in numeric order.
+
+## 2. Create a task class
+
+Create `tasks/Greet.ts`:
+
+```typescript
+import { BaseTask, type TaskResult } from '@db-lyon/flowkit';
+
+interface GreetOptions {
+  name: string;
+}
+
+export default class Greet extends BaseTask<GreetOptions> {
+  get taskName() {
+    return 'greet';
+  }
+
+  async execute(): Promise<TaskResult> {
+    const message = `Hello, ${this.options.name}!`;
+    this.logger.info(message);
+    return { success: true, data: { message } };
+  }
+}
+```
+
+Every task must:
+1. Extend `BaseTask<TOptions>`
+2. Implement the `taskName` getter
+3. Implement the async `execute()` method returning a `TaskResult`
+
+## 3. Wire it up
+
+Create `run.ts`:
+
+```typescript
+import {
+  loadConfig,
+  EngineConfigSchema,
+  TaskRegistry,
+  FlowRunner,
+} from '@db-lyon/flowkit';
+
+// Load and validate the YAML config
+const { config } = loadConfig({
+  filename: 'pipeline.yml',
+  schema: EngineConfigSchema,
+  configDir: './config',
+});
+
+// Create a registry — flowkit uses this to resolve class_path → constructor
+const registry = new TaskRegistry();
+
+// Create the flow runner
+const runner = new FlowRunner({
+  tasks: config.tasks,
+  flows: config.flows,
+  registry,
+  context: {},
+});
+
+// Run the flow
+const result = await runner.run({ flowName: 'hello' });
+
+if (result.success) {
+  console.log('Flow completed successfully');
+} else {
+  console.error('Flow failed:', result.error?.message);
+}
+```
+
+## 4. Run it
+
+```bash
+npx tsx run.ts
+```
+
+The `greet` task's `class_path: tasks.Greet` tells flowkit to look for `tasks/Greet.ts` (or `.js`) relative to `process.cwd()`. It dynamically imports the file and instantiates the default export.
+
+## How task resolution works
+
+When the flow runner encounters a task step, it:
+
+1. Looks up the task name in `config.tasks` to get the `class_path`
+2. Checks the registry for a constructor registered under that `class_path` or name
+3. If not found, converts the dotted path to a file path and dynamically imports it (e.g., `tasks.Greet` → `tasks/Greet.ts`)
+4. Instantiates the task with the merged options (task defaults + step overrides)
+5. Calls `task.run()` which runs `validate()` → `execute()` → returns the result
+
+## Explicit registration
+
+Instead of relying on dynamic filesystem resolution, you can register tasks directly:
+
+```typescript
+import Greet from './tasks/Greet.js';
+
+const registry = new TaskRegistry();
+registry.register('greet', Greet as any);
+
+// Or by class_path
+registry.registerClassPath('tasks.Greet', Greet as any);
+
+// Or bulk register
+registry.registerAll({
+  greet: Greet as any,
+  // ...more tasks
+});
+```
+
+## Adding a logger
+
+Flowkit accepts any logger with `debug`, `info`, `warn`, `error`, and `child` methods (pino, winston, etc.):
+
+```typescript
+import pino from 'pino';
+
+const logger = pino();
+
+const runner = new FlowRunner({
+  tasks: config.tasks,
+  flows: config.flows,
+  registry,
+  context: { logger },
+  logger,
+});
+```
+
+The context logger is passed to each task instance. The runner logger is used for flow-level logging. Both fall back to a silent no-op logger if omitted.
+
+## Next steps
+
+- [Custom tasks](custom-tasks.md) — validation, error handling, and the ShellTask
+- [Configuration](configuration.md) — layered configs, environment overlays, deep merge
+- [API reference](api-reference.md) — full type and function docs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@db-lyon/flowkit",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "YAML-configured task and flow orchestration engine",
   "type": "module",
   "main": "dist/index.js",
@@ -13,7 +13,8 @@
     "./dag": "./dist/dag/index.js"
   },
   "files": [
-    "/dist"
+    "/dist",
+    "/docs"
   ],
   "scripts": {
     "build": "tsc -b",

package/dist/flow/references.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"references.d.ts","sourceRoot":"","sources":["../../src/flow/references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,iDAAiD;IACjD,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAQD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,gBAAgB,GAAG,CAAC,CAcvE"}

package/dist/flow/references.js.map

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