@unlaxer/tramli 1.5.2 → 1.6.0

package/dist/cjs/skeleton-generator.d.ts

@@ -0,0 +1,10 @@
+import type { FlowDefinition } from './flow-definition.js';
+export type TargetLanguage = 'java' | 'typescript' | 'rust';
+/**
+ * Generates Processor skeleton code from a FlowDefinition's requires/produces contracts.
+ */
+export declare class SkeletonGenerator {
+    static generate<S extends string>(def: FlowDefinition<S>, lang: TargetLanguage): string;
+    private static genProcessor;
+    private static genGuard;
+}

package/dist/cjs/skeleton-generator.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkeletonGenerator = void 0;
+/**
+ * Generates Processor skeleton code from a FlowDefinition's requires/produces contracts.
+ */
+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`;
+    }
+}
+exports.SkeletonGenerator = SkeletonGenerator;
+function lcFirst(s) { return s.charAt(0).toLowerCase() + s.slice(1); }

package/dist/cjs/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/cjs/tramli.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Tramli = void 0;
+const flow_definition_js_1 = require("./flow-definition");
+const flow_engine_js_1 = require("./flow-engine");
+class Tramli {
+    static define(name, stateConfig) {
+        return new flow_definition_js_1.Builder(name, stateConfig);
+    }
+    static engine(store) {
+        return new flow_engine_js_1.FlowEngine(store);
+    }
+}
+exports.Tramli = Tramli;

package/dist/cjs/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/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/esm/data-flow-graph.d.ts

@@ -0,0 +1,92 @@
+import type { FlowDefinition } from './flow-definition.js';
+import type { FlowKey } from './flow-key.js';
+import type { StateProcessor } from './types.js';
+import type { FlowContext } from './flow-context.js';
+export interface NodeInfo<S extends string> {
+    name: string;
+    fromState: S;
+    toState: S;
+    kind: 'processor' | 'guard' | 'branch' | 'initial';
+}
+/**
+ * Bipartite graph of data types (FlowKey) and processors/guards.
+ * Built automatically during FlowDefinition.build().
+ */
+export declare class DataFlowGraph<S extends string> {
+    private readonly _availableAtState;
+    private readonly _producers;
+    private readonly _consumers;
+    private readonly _allProduced;
+    private readonly _allConsumed;
+    private constructor();
+    /** Data types available in context when the flow reaches the given state. */
+    availableAt(state: S): Set<string>;
+    /** Processors/guards that produce the given type. */
+    producersOf(key: FlowKey<unknown>): NodeInfo<S>[];
+    /** Processors/guards that consume (require) the given type. */
+    consumersOf(key: FlowKey<unknown>): NodeInfo<S>[];
+    /** Types produced but never required by any downstream processor/guard. */
+    deadData(): Set<string>;
+    /** Data lifetime: which states a type is first produced and last consumed. */
+    lifetime(key: FlowKey<unknown>): {
+        firstProduced: S;
+        lastConsumed: S;
+    } | null;
+    /** Context pruning hints: for each state, types available but not required at that state. */
+    pruningHints(): Map<S, Set<string>>;
+    /**
+     * Check if processor B can replace processor A without breaking data-flow.
+     * B is compatible with A if: B requires no more than A, and B produces at least what A produces.
+     */
+    static isCompatible<S extends string>(a: {
+        requires: FlowKey<unknown>[];
+        produces: FlowKey<unknown>[];
+    }, b: {
+        requires: FlowKey<unknown>[];
+        produces: FlowKey<unknown>[];
+    }): boolean;
+    /**
+     * Verify a processor's declared requires/produces against actual context usage.
+     * Returns list of violations (empty = OK).
+     */
+    static verifyProcessor<S extends string>(processor: StateProcessor<S>, ctx: FlowContext): Promise<string[]>;
+    /** All type nodes in the graph. */
+    allTypes(): Set<string>;
+    /**
+     * Assert that a flow instance's context satisfies the data-flow invariant.
+     * Returns list of missing type keys (empty = OK).
+     */
+    assertDataFlow(ctx: FlowContext, currentState: S): string[];
+    /** Impact analysis: all producers and consumers of a given type. */
+    impactOf(key: FlowKey<unknown>): {
+        producers: NodeInfo<S>[];
+        consumers: NodeInfo<S>[];
+    };
+    /** Parallelism hints: pairs of processors with no data dependency. */
+    parallelismHints(): [string, string][];
+    /** Structured JSON representation. */
+    toJson(): string;
+    /** Generate Mermaid data-flow diagram. */
+    toMermaid(): string;
+    /** Recommended migration order: processors sorted by dependency (fewest first). */
+    migrationOrder(): string[];
+    /** Generate Markdown migration checklist. */
+    toMarkdown(): string;
+    /** Test scaffold: for each processor, list required type names. */
+    testScaffold(): Map<string, string[]>;
+    /** Generate data-flow invariant assertions as strings. */
+    generateInvariantAssertions(): string[];
+    /** Cross-flow map: types that one flow produces and another requires. */
+    static crossFlowMap(...graphs: DataFlowGraph<any>[]): string[];
+    /** Diff two data-flow graphs. */
+    static diff(before: DataFlowGraph<any>, after: DataFlowGraph<any>): {
+        addedTypes: Set<string>;
+        removedTypes: Set<string>;
+        addedEdges: Set<string>;
+        removedEdges: Set<string>;
+    };
+    private static collectEdges;
+    /** Version compatibility: check if v1 instances can resume on v2 definition. */
+    static versionCompatibility<S extends string>(before: DataFlowGraph<S>, after: DataFlowGraph<S>): string[];
+    static build<S extends string>(def: FlowDefinition<S>, initiallyAvailable: string[]): DataFlowGraph<S>;
+}