This is an automated email from the ASF dual-hosted git repository. ebenizzy pushed a commit to branch feat/typescript-implementation in repository https://gitbox.apache.org/repos/asf/burr.git
commit 9fc27aca63fa70de256b474f2c72276244d70597 Author: Elijah ben Izzy <[email protected]> AuthorDate: Tue Dec 23 13:39:33 2025 -0800 Adds core scaffolding for typesscript project. This is very much a WIP. --- .pre-commit-config.yaml | 22 ++++++++- typescript/.eslintrc.json | 22 +++++++++ typescript/.gitignore | 37 +++++++++++++++ typescript/.prettierrc.json | 9 ++++ typescript/README.md | 54 ++++++++++++++++++++++ typescript/package.json | 33 +++++++++++++ typescript/packages/burr-core/README.md | 31 +++++++++++++ typescript/packages/burr-core/jest.config.js | 27 +++++++++++ typescript/packages/burr-core/package.json | 38 +++++++++++++++ typescript/packages/burr-core/src/action.ts | 21 +++++++++ .../packages/burr-core/src/application-builder.ts | 21 +++++++++ typescript/packages/burr-core/src/application.ts | 21 +++++++++ typescript/packages/burr-core/src/graph.ts | 21 +++++++++ typescript/packages/burr-core/src/index.ts | 21 +++++++++ typescript/packages/burr-core/src/lifecycle.ts | 21 +++++++++ typescript/packages/burr-core/src/persistence.ts | 21 +++++++++ typescript/packages/burr-core/src/serde.ts | 21 +++++++++ typescript/packages/burr-core/src/state.ts | 21 +++++++++ typescript/packages/burr-core/src/types.ts | 21 +++++++++ typescript/packages/burr-core/tsconfig.json | 10 ++++ typescript/tsconfig.json | 25 ++++++++++ 21 files changed, 517 insertions(+), 1 deletion(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7905de2c..d3d5df32 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -18,7 +18,7 @@ # $ cd /PATH/TO/REPO # $ pre-commit install -exclude: '^telemetry/ui|^burr/tracking/server/demo_data(/|$)' +exclude: '^telemetry/ui|^typescript/|^burr/tracking/server/demo_data(/|$)' repos: - repo: https://github.com/ambv/black rev: 23.11.0 @@ -56,6 +56,26 @@ repos: rev: 6.1.0 hooks: - id: flake8 + # ESLint for TypeScript + - repo: https://github.com/pre-commit/mirrors-eslint + rev: v8.56.0 + hooks: + - id: eslint + files: ^typescript/.*\.[jt]sx?$ + types: [file] + args: ['--fix'] + additional_dependencies: + - [email protected] + - '@typescript-eslint/[email protected]' + - '@typescript-eslint/[email protected]' + - [email protected] + # Prettier for TypeScript + - repo: https://github.com/pre-commit/mirrors-prettier + rev: v3.1.0 + hooks: + - id: prettier + files: ^typescript/.*\.(ts|tsx|js|jsx|json|md)$ + args: ['--write'] - repo: local # This is a bit of a hack, but its the easiest way to get it to all run together # https://stackoverflow.com/questions/64001471/pylint-with-pre-commit-and-esllint-with-husky diff --git a/typescript/.eslintrc.json b/typescript/.eslintrc.json new file mode 100644 index 00000000..c06b1c01 --- /dev/null +++ b/typescript/.eslintrc.json @@ -0,0 +1,22 @@ +{ + "parser": "@typescript-eslint/parser", + "extends": [ + "eslint:recommended", + "plugin:@typescript-eslint/recommended" + ], + "plugins": ["@typescript-eslint"], + "env": { + "node": true, + "es6": true + }, + "parserOptions": { + "ecmaVersion": 2020, + "sourceType": "module" + }, + "rules": { + "@typescript-eslint/explicit-function-return-type": "warn", + "@typescript-eslint/no-explicit-any": "warn", + "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }] + } +} + diff --git a/typescript/.gitignore b/typescript/.gitignore new file mode 100644 index 00000000..895f3e43 --- /dev/null +++ b/typescript/.gitignore @@ -0,0 +1,37 @@ +# Dependencies +node_modules/ +package-lock.json +yarn.lock +pnpm-lock.yaml + +# Build outputs +dist/ +build/ +*.tsbuildinfo + +# Testing +coverage/ +.nyc_output/ + +# IDEs +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Environment +.env +.env.local +.env.*.local + diff --git a/typescript/.prettierrc.json b/typescript/.prettierrc.json new file mode 100644 index 00000000..053c69d3 --- /dev/null +++ b/typescript/.prettierrc.json @@ -0,0 +1,9 @@ +{ + "semi": true, + "trailingComma": "es5", + "singleQuote": true, + "printWidth": 100, + "tabWidth": 2, + "useTabs": false +} + diff --git a/typescript/README.md b/typescript/README.md new file mode 100644 index 00000000..ab74dad8 --- /dev/null +++ b/typescript/README.md @@ -0,0 +1,54 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# Apache Burr (TypeScript) + +TypeScript implementation of Apache Burr - a framework for building applications that make decisions (chatbots, agents, simulations, etc.) from simple building blocks. + +## Status + +🚧 **Work in Progress** - This is an active port of the Python implementation. APIs may change. + +## Structure + +- `packages/burr-core/` - Core library (state machine, actions, application) +- `examples/` - TypeScript examples +- `tests/` - Integration tests + +## Getting Started + +```bash +# Install dependencies +npm install + +# Build all packages +npm run build + +# Run tests +npm test +``` + +## Documentation + +See the main [Burr documentation](https://burr.apache.org/) for concepts and guides. TypeScript-specific documentation coming soon. + +## Compatibility + +This implementation aims to match the Python version's core functionality with TypeScript idioms and best practices. + diff --git a/typescript/package.json b/typescript/package.json new file mode 100644 index 00000000..94e036c2 --- /dev/null +++ b/typescript/package.json @@ -0,0 +1,33 @@ +{ + "name": "@apache-burr/workspace", + "version": "0.1.0", + "private": true, + "description": "Apache Burr TypeScript implementation workspace", + "workspaces": [ + "packages/*" + ], + "scripts": { + "build": "npm run build --workspaces", + "test": "npm run test --workspaces", + "lint": "eslint . --ext .ts,.tsx", + "format": "prettier --write \"**/*.{ts,tsx,json,md}\"" + }, + "devDependencies": { + "@types/node": "^20.0.0", + "@typescript-eslint/eslint-plugin": "^6.0.0", + "@typescript-eslint/parser": "^6.0.0", + "eslint": "^8.0.0", + "prettier": "^3.0.0", + "typescript": "^5.3.0" + }, + "engines": { + "node": ">=18.0.0" + }, + "license": "Apache-2.0", + "repository": { + "type": "git", + "url": "https://github.com/apache/burr.git";, + "directory": "typescript" + } +} + diff --git a/typescript/packages/burr-core/README.md b/typescript/packages/burr-core/README.md new file mode 100644 index 00000000..60194989 --- /dev/null +++ b/typescript/packages/burr-core/README.md @@ -0,0 +1,31 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +# @apache-burr/core + +Core TypeScript library for Apache Burr - build state machines with simple functions. + +## Status + +🚧 **Not Yet Implemented** - This package is scaffolding for the TypeScript port. + +## License + +Apache License 2.0 + diff --git a/typescript/packages/burr-core/jest.config.js b/typescript/packages/burr-core/jest.config.js new file mode 100644 index 00000000..89929cd8 --- /dev/null +++ b/typescript/packages/burr-core/jest.config.js @@ -0,0 +1,27 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +module.exports = { + preset: 'ts-jest', + testEnvironment: 'node', + roots: ['<rootDir>/src'], + testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'], + collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts', '!src/**/*.test.ts'], +}; + diff --git a/typescript/packages/burr-core/package.json b/typescript/packages/burr-core/package.json new file mode 100644 index 00000000..634d6c92 --- /dev/null +++ b/typescript/packages/burr-core/package.json @@ -0,0 +1,38 @@ +{ + "name": "@apache-burr/core", + "version": "0.1.0", + "description": "Core state machine library for Apache Burr (TypeScript)", + "main": "dist/index.js", + "types": "dist/index.d.ts", + "scripts": { + "build": "tsc", + "test": "jest", + "test:watch": "jest --watch", + "lint": "eslint src --ext .ts", + "clean": "rm -rf dist" + }, + "keywords": [ + "state-machine", + "workflow", + "llm", + "agent", + "burr" + ], + "author": "Apache Burr Contributors", + "license": "Apache-2.0", + "devDependencies": { + "@types/jest": "^29.0.0", + "jest": "^29.0.0", + "ts-jest": "^29.0.0", + "typescript": "^5.3.0" + }, + "repository": { + "type": "git", + "url": "https://github.com/apache/burr.git";, + "directory": "typescript/packages/burr-core" + }, + "engines": { + "node": ">=18.0.0" + } +} + diff --git a/typescript/packages/burr-core/src/action.ts b/typescript/packages/burr-core/src/action.ts new file mode 100644 index 00000000..3b6900da --- /dev/null +++ b/typescript/packages/burr-core/src/action.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// Action definitions and decorators for Burr (async-only) + diff --git a/typescript/packages/burr-core/src/application-builder.ts b/typescript/packages/burr-core/src/application-builder.ts new file mode 100644 index 00000000..de0cfd7f --- /dev/null +++ b/typescript/packages/burr-core/src/application-builder.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// Application builder with fluent API + diff --git a/typescript/packages/burr-core/src/application.ts b/typescript/packages/burr-core/src/application.ts new file mode 100644 index 00000000..d9c9d63d --- /dev/null +++ b/typescript/packages/burr-core/src/application.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// Application runtime and execution engine + diff --git a/typescript/packages/burr-core/src/graph.ts b/typescript/packages/burr-core/src/graph.ts new file mode 100644 index 00000000..4b1dd20a --- /dev/null +++ b/typescript/packages/burr-core/src/graph.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// Graph structure and transition logic + diff --git a/typescript/packages/burr-core/src/index.ts b/typescript/packages/burr-core/src/index.ts new file mode 100644 index 00000000..a5c30209 --- /dev/null +++ b/typescript/packages/burr-core/src/index.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// Public API exports for @apache-burr/core + diff --git a/typescript/packages/burr-core/src/lifecycle.ts b/typescript/packages/burr-core/src/lifecycle.ts new file mode 100644 index 00000000..ef97d6ca --- /dev/null +++ b/typescript/packages/burr-core/src/lifecycle.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// Lifecycle hooks for application and action execution + diff --git a/typescript/packages/burr-core/src/persistence.ts b/typescript/packages/burr-core/src/persistence.ts new file mode 100644 index 00000000..2beec896 --- /dev/null +++ b/typescript/packages/burr-core/src/persistence.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// State persistence interfaces and implementations + diff --git a/typescript/packages/burr-core/src/serde.ts b/typescript/packages/burr-core/src/serde.ts new file mode 100644 index 00000000..31d25872 --- /dev/null +++ b/typescript/packages/burr-core/src/serde.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// Serialization and deserialization utilities + diff --git a/typescript/packages/burr-core/src/state.ts b/typescript/packages/burr-core/src/state.ts new file mode 100644 index 00000000..dfce1dbc --- /dev/null +++ b/typescript/packages/burr-core/src/state.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// State management for Burr applications + diff --git a/typescript/packages/burr-core/src/types.ts b/typescript/packages/burr-core/src/types.ts new file mode 100644 index 00000000..956e11a6 --- /dev/null +++ b/typescript/packages/burr-core/src/types.ts @@ -0,0 +1,21 @@ +/** + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +// Core type definitions for Burr + diff --git a/typescript/packages/burr-core/tsconfig.json b/typescript/packages/burr-core/tsconfig.json new file mode 100644 index 00000000..ef7a3468 --- /dev/null +++ b/typescript/packages/burr-core/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "outDir": "./dist", + "rootDir": "./src" + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} + diff --git a/typescript/tsconfig.json b/typescript/tsconfig.json new file mode 100644 index 00000000..6cd6e653 --- /dev/null +++ b/typescript/tsconfig.json @@ -0,0 +1,25 @@ +{ + "compilerOptions": { + "target": "ES2020", + "module": "commonjs", + "lib": ["ES2020"], + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "outDir": "./dist", + "rootDir": "./", + "composite": true, + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "moduleResolution": "node", + "resolveJsonModule": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": true + }, + "exclude": ["node_modules", "dist", "**/*.test.ts"] +} +
