Amey/typescript implementation extension

[Kamehameya]

TypeScript implementation of @apache-burr/core

Ground-up TypeScript port of Burr's core runtime — state machine engine, actions, graph, application execution, and all cross-cutting concerns (lifecycle hooks, persistence, streaming, tracing, parallelism). Uses Zod schemas for runtime validation and TypeScript generics for compile-time safety.

Changes

• State (state.ts): Immutable, Zod-validated container with three-schema design (main/readable/writable). Operations pattern for update, append, extend, increment, subset, merge. Copy-on-write via structuredClone.
• Actions (action.ts): Two-phase run() → update() pattern with schema-validated reads/writes/inputs/result. Factory function with overloads for full and update-only actions.
• Graph (graph.ts): GraphBuilder with fluent API, unconditional/conditional/terminal transitions. Type-level accumulation of action state schemas.
• Application (application.ts, application-builder.ts): Fork→Launch→Gather→Commit four-phase execution. step(), run(), iterate(), streamStep(). Framework metadata (appMetadata/executionMetadata) injected into state. Immutable builder with compile-time graph/state compatibility checks.
• Lifecycle hooks (lifecycle.ts): 11 async hook types mirroring Python's burr/lifecycle/base.py. LifecycleAdapterSet dispatcher with duck-typed dispatch.
• Streaming (streaming.ts): StreamingAction with AsyncGenerator-based streamRun(). StreamingResultContainer for buffered iteration + finalization.
• Persistence (persistence.ts): StateLoader/StateSaver/StatePersister interfaces. InMemoryPersister for testing. PersisterHook lifecycle integration. initializeFrom() for state resumption.
• Serialization (serde.ts): Tagged-value convention for non-JSON types (Date, Map, Set, RegExp, BigInt). Extensible via custom serializers/deserializers.
• Tracing (tracing.ts): ActionSpan/ActionSpanTracer/TracerFactory with AsyncLocalStorage context propagation.
• Parallelism (parallelism.ts): RunnableGraph, SubGraphTask, TaskBasedParallelAction, MapActions, MapStates, MapActionsAndStates. Promise.all() execution.
• Type utilities (type-utils.ts, schema-utils.ts): Advanced type machinery for compile-time safety + runtime schema extension helpers.
• Project scaffolding: monorepo under typescript/, ESLint, Prettier, Jest config, pre-commit hook update.

How I tested this

• ~4,500 lines of Jest unit tests covering state, action, graph, application, execution, lifecycle, streaming, persistence, serde, tracing, and parallelism
• Custom compile-time type test framework with ~40 individual type test files validating that correct code compiles and incorrect code produces expected type errors
• Manual testing via scratch-examples/counter-hw.ts

To run locally:

# Clone and checkout
git fetch origin
git checkout amey/typescript-implementation-extension

# Install dependencies
cd typescript
npm install

# Run the full test suite
cd packages/burr-core
npx jest

# Run just the compile-time type tests
npx jest src/__tests__/type-tests/runner.test.ts

# Verify it compiles cleanly
npx tsc --noEmit

Notes

• All execution is async-only (Python has sync + async variants)
• Zod v4 is the only runtime dependency
• README.md updated with comprehensive feature parity tables vs Python
• Phase 1 (core) and Phase 2 (extensions) complete; Phase 3 (DX polish) and Phase 4 (production adapters) remain
• Some features not yet ported: state.wipe(), action tags, graph validation/cycle detection, visualize(), concrete persistence backends (SQLite, Postgres, etc.), tracking clients
• TODO comments flagged in code for: reserved metadata key validation at build time, entrypoint reads validation, initializeFrom resume logic

Checklist

• PR has an informative and human-readable title
• Changes are limited to a single goal (no scope creep)
• Code passed the pre-commit check & code is left cleaner/nicer than when first encountered
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged / future TODOs are captured in comments
• Project documentation has been updated if adding/changing functionality

[skrawcz]

? otherwise needs apache license.

[skrawcz]

PR description? How can I run this locally?

[github-actions]

This PR has been inactive for 19 days after receiving review feedback.
Converting to draft.

Please mark it as ready for review when you have addressed the comments.
If no activity occurs within 90 days, it will be closed automatically.

[Kamehameya]

PR description? How can I run this locally?

Added the description

Testing:

git checkout amey/typescript-implementation-extension
cd typescript/packages/burr-core
npm install
npx jest --no-coverage

Run the integration test specifically (mirrors Python's tests/integration_tests/test_app.py):

npx jest src/__tests__/integration.test.ts --no-coverage

Run the hello-world counter demo (port of examples/hello-world-counter/application.py):

npx ts-node scratch-examples/hello-world-counter.ts