@unlaxer/tramli 1.5.2 → 1.6.0

package/dist/esm/skeleton-generator.js

@@ -0,0 +1,44 @@
+/**
+ * Generates Processor skeleton code from a FlowDefinition's requires/produces contracts.
+ */
+export class SkeletonGenerator {
+    static generate(def, lang) {
+        const lines = [
+            `// Skeleton generated from flow: ${def.name}`,
+            `// Language: ${lang}`,
+            '',
+        ];
+        const seen = new Set();
+        for (const t of def.transitions) {
+            if (t.processor && !seen.has(t.processor.name)) {
+                seen.add(t.processor.name);
+                lines.push(this.genProcessor(t.processor.name, t.processor.requires, t.processor.produces, lang));
+            }
+            if (t.guard && !seen.has(t.guard.name)) {
+                seen.add(t.guard.name);
+                lines.push(this.genGuard(t.guard.name, t.guard.requires, t.guard.produces, lang));
+            }
+        }
+        return lines.join('\n');
+    }
+    static genProcessor(name, reqs, prods, lang) {
+        if (lang === 'typescript') {
+            return `const ${lcFirst(name)}: StateProcessor<S> = {\n  name: '${name}',\n  requires: [${reqs.join(', ')}],\n  produces: [${prods.join(', ')}],\n  process(ctx: FlowContext) {\n${reqs.map(r => `    const ${lcFirst(r)} = ctx.get(${r});`).join('\n')}\n    // TODO: implement\n${prods.map(p => `    // ctx.put(${p}, { ... });`).join('\n')}\n  },\n};\n`;
+        }
+        if (lang === 'java') {
+            return `static final StateProcessor ${name.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase()} = new StateProcessor() {\n    @Override public String name() { return "${name}"; }\n    @Override public Set<Class<?>> requires() { return Set.of(${reqs.map(r => r + '.class').join(', ')}); }\n    @Override public Set<Class<?>> produces() { return Set.of(${prods.map(p => p + '.class').join(', ')}); }\n    @Override public void process(FlowContext ctx) {\n        // TODO: implement\n    }\n};\n`;
+        }
+        // rust
+        return `struct ${name};\nimpl StateProcessor<S> for ${name} {\n    fn name(&self) -> &str { "${name}" }\n    fn requires(&self) -> Vec<TypeId> { requires![${reqs.join(', ')}] }\n    fn produces(&self) -> Vec<TypeId> { requires![${prods.join(', ')}] }\n    fn process(&self, ctx: &mut FlowContext) -> Result<(), FlowError> {\n        todo!()\n    }\n}\n`;
+    }
+    static genGuard(name, reqs, prods, lang) {
+        if (lang === 'typescript') {
+            return `const ${lcFirst(name)}: TransitionGuard<S> = {\n  name: '${name}',\n  requires: [${reqs.join(', ')}],\n  produces: [${prods.join(', ')}],\n  maxRetries: 3,\n  validate(ctx: FlowContext): GuardOutput {\n    // TODO: implement\n    return { type: 'accepted' };\n  },\n};\n`;
+        }
+        if (lang === 'java') {
+            return `static final TransitionGuard ${name.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase()} = new TransitionGuard() {\n    @Override public String name() { return "${name}"; }\n    @Override public Set<Class<?>> requires() { return Set.of(${reqs.map(r => r + '.class').join(', ')}); }\n    @Override public Set<Class<?>> produces() { return Set.of(${prods.map(p => p + '.class').join(', ')}); }\n    @Override public int maxRetries() { return 3; }\n    @Override public GuardOutput validate(FlowContext ctx) {\n        return new GuardOutput.Accepted();\n    }\n};\n`;
+        }
+        return `struct ${name};\nimpl TransitionGuard<S> for ${name} {\n    fn name(&self) -> &str { "${name}" }\n    fn requires(&self) -> Vec<TypeId> { requires![${reqs.join(', ')}] }\n    fn produces(&self) -> Vec<TypeId> { requires![${prods.join(', ')}] }\n    fn validate(&self, ctx: &FlowContext) -> GuardOutput {\n        GuardOutput::Accepted { data: HashMap::new() }\n    }\n}\n`;
+    }
+}
+function lcFirst(s) { return s.charAt(0).toLowerCase() + s.slice(1); }

package/dist/esm/tramli.d.ts

@@ -0,0 +1,8 @@
+import type { StateConfig } from './types.js';
+import { Builder } from './flow-definition.js';
+import { FlowEngine } from './flow-engine.js';
+import type { InMemoryFlowStore } from './in-memory-flow-store.js';
+export declare class Tramli {
+    static define<S extends string>(name: string, stateConfig: Record<S, StateConfig>): Builder<S>;
+    static engine(store: InMemoryFlowStore): FlowEngine;
+}

package/dist/esm/tramli.js

@@ -0,0 +1,10 @@
+import { Builder } from './flow-definition.js';
+import { FlowEngine } from './flow-engine.js';
+export class Tramli {
+    static define(name, stateConfig) {
+        return new Builder(name, stateConfig);
+    }
+    static engine(store) {
+        return new FlowEngine(store);
+    }
+}

package/dist/esm/types.d.ts

@@ -0,0 +1,75 @@
+import type { FlowKey } from './flow-key.js';
+import type { FlowContext } from './flow-context.js';
+/** State configuration: terminal and initial flags for each state. */
+export type StateConfig = {
+    terminal: boolean;
+    initial: boolean;
+};
+/** Guard output — discriminated union (Java: sealed interface GuardOutput). */
+export type GuardOutput = {
+    type: 'accepted';
+    data?: Map<string, unknown>;
+} | {
+    type: 'rejected';
+    reason: string;
+} | {
+    type: 'expired';
+};
+/** Transition types. */
+export type TransitionType = 'auto' | 'external' | 'branch' | 'sub_flow';
+/** A single transition in the flow definition. */
+export interface Transition<S extends string> {
+    from: S;
+    to: S;
+    type: TransitionType;
+    processor?: StateProcessor<S>;
+    guard?: TransitionGuard<S>;
+    branch?: BranchProcessor<S>;
+    branchTargets: Map<string, S>;
+    subFlowDefinition?: import('./flow-definition.js').FlowDefinition<any>;
+    exitMappings?: Map<string, S>;
+}
+/**
+ * Processes a state transition.
+ *
+ * Processors SHOULD be fast and avoid external I/O.
+ * If a processor throws, the engine restores context and routes to error transition.
+ */
+export interface StateProcessor<S extends string> {
+    name: string;
+    requires: FlowKey<unknown>[];
+    produces: FlowKey<unknown>[];
+    process(ctx: FlowContext): Promise<void> | void;
+}
+/**
+ * Guards an external transition. Pure function — must not mutate FlowContext.
+ *
+ * TTL vs GuardOutput.expired: FlowInstance TTL is checked at resumeAndExecute
+ * entry (flow-level). GuardOutput 'expired' is guard-level for business logic.
+ */
+export interface TransitionGuard<S extends string> {
+    name: string;
+    requires: FlowKey<unknown>[];
+    produces: FlowKey<unknown>[];
+    maxRetries: number;
+    validate(ctx: FlowContext): Promise<GuardOutput> | GuardOutput;
+}
+/** Decides which branch to take based on FlowContext state. */
+export interface BranchProcessor<S extends string> {
+    name: string;
+    requires: FlowKey<unknown>[];
+    decide(ctx: FlowContext): Promise<string> | string;
+}
+/**
+ * Persistence contract for flow instances.
+ *
+ * Threading: FlowEngine assumes single-threaded access per flow instance.
+ * Atomicity: create/save and recordTransition form a logical unit.
+ * If partial writes occur, save is authoritative over the transition log.
+ */
+export interface FlowStore {
+    create(flow: unknown): void | Promise<void>;
+    loadForUpdate<S extends string>(flowId: string): unknown | undefined | Promise<unknown | undefined>;
+    save(flow: unknown): void | Promise<void>;
+    recordTransition(flowId: string, from: string | null, to: string, trigger: string, ctx: FlowContext): void | Promise<void>;
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "@unlaxer/tramli",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Constrained flow engine — state machines that prevent invalid transitions at build time",
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/esm/index.d.ts"
     }
   },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
   "files": ["dist"],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node scripts/fix-cjs.cjs",
     "test": "vitest run",
     "prepublishOnly": "npm run build && npm test"
   },