@elaraai/east 0.0.1-beta.9 → 1.0.0

package/README.md

@@ -7,26 +7,20 @@
 Delivering a complete business solution requires a wide range of technologies and activities: data integrations, mathematical optimization, machine learning, simulation, user interfaces, authentication & authorization, hosting, managing data consistency, auditing, etc.
 Multiple programming environments are required to solve any given business problem - for example you may use JavaScript for web front ends and python for training and evaluating machine learning models.
 
-East is designed to make it easy to fuse different technologies together by focussing on a simple yet powerful structural type system which makes all the bolierplate and plumbing work disappear, letting you spend more time solving real-world problems.
+East is designed to make it easy to fuse different technologies together by focussing on a simple yet powerful structural type system which makes all the boilerplate and plumbing work disappear, letting you spend more time solving real-world problems.
 East is intentionally a simple language that is fast to learn and straightforward to implement in new runtimes.
 
 ## Features
 
-- **🔒 Static Typing**: All types declared explicitly for speed and correctness
-- **🎯 Structural Typing**: Lightweight and easy to use
-- **🚀 Portable IR**: Compile to JavaScript, with Julia and Python backends coming soon
-- **🔐 Controlled Side Effects**: Secure execution with platform-defined effects
-- **🤖 LLM Friendly**: Designed for code generation with clear, composable TypeScript API & MCP integration
-- **📦 Minimal Dependencies**: Single runtime dependency (sorted-btree for efficient collections)
-- **🛡️ Total Ordering**: All types (even floats with NaN) have defined comparisons
-- **🔄 Serializable**: All data can be serialized, functions can be transmitted as IR
+- **Static Typing**: All types, functions and values declared explicitly for speed and correctness
+- **Structural Typing**: Expressive type system with recursive types, first-class functions and polymorphic variants
+- **Portable IR**: Compile to JavaScript, Python and Julia
+- **Controlled Side Effects**: Secure execution with cross-language platform-defined effects
+- **LLM Friendly**: Designed for AI with clear, composable yet stochastic friendly aliases
+- **Serializable**: All data can be serialized; functions and closures can be transmitted as IR
+- **Minimal Dependencies**: Single runtime dependency (sorted-btree for efficient collections)
+- **Total Ordering**: All types have defined comparisons that are consistent across all language targets
 
-## Development status
-
-Note that at this stage of development, East does not have a concrete syntax.
-Code is created through a TypeScript fluent interface.
-Otherwise, East is quite usable and works end-to-end with multiple backend implementations (including a natively compiled one).
-The East language is not considered "stable", and the implementation here may undergo breaking changes.
 
 ## Quick Start
 
@@ -65,7 +59,7 @@ const calculateRevenue = East.function(
         const revenueByProduct = sales.groupSum(
             // Group by product name
             ($, sale) => sale.product,
-            // Sum quantity × price    
+            // Sum quantity × price
             ($, sale) => sale.quantity.multiply(sale.price)
         );
 
@@ -108,6 +102,11 @@ East supports a rich type system optimized for business logic and data processin
 | `SetType<K>` | `Set<ValueTypeOf<K>>` | **Mutable** | Sorted set |
 | `DictType<K, V>` | `Map<ValueTypeOf<K>, ValueTypeOf<V>>` | **Mutable** | Sorted dictionary |
 | `RefType<T>` | `ref<ValueTypeOf<T>>` | **Mutable** | Refcell, mutable box |
+| **Numeric Arrays** | | | |
+| `VectorType<FloatType>` | `Float64Array` | **Mutable** | Dense float vector |
+| `VectorType<IntegerType>` | `BigInt64Array` | **Mutable** | Dense integer vector |
+| `VectorType<BooleanType>` | `Uint8ClampedArray` | **Mutable** | Dense boolean vector |
+| `MatrixType<T>` | `matrix<TypedArray>` | **Mutable** | Dense 2D matrix (row-major) |
 | **Compound types** | | | |
 | `StructType<Fields>` | `{...}` | Immutable | Product type (records) |
 | `VariantType<Cases>` | `variant` | Immutable | Sum type (tagged unions) |
@@ -118,7 +117,7 @@ East supports a rich type system optimized for business logic and data processin
 
 ## Documentation
 
-- **[USAGE.md](USAGE.md)** - Comprehensive developer guide with API reference
+- **[SKILL.md](SKILL.md)** - Comprehensive guide with API and example reference
 - **[LICENSE.md](LICENSE.md)** - Dual licensing information (AGPL-3.0 / Commercial)
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute to East
 - **[CLA.md](CLA.md)** - Contributor License Agreement
@@ -130,22 +129,22 @@ East supports a rich type system optimized for business logic and data processin
 East code runs in a controlled environment. You define **platform functions** that your East code can call:
 
 ```typescript
-// Define platform function helper
+// Define platform functions
 const log = East.platform("log", [StringType], NullType);
 const readFile = East.platform("readFile", [StringType], StringType);
 
 // Provide implementations
-const platform = {
-    log: (msg: string) => console.log(msg),
-    readFile: (path: string) => fs.readFileSync(path, 'utf-8')
-};
+const platform = [
+    log.implement((msg: string) => console.log(msg)),
+    readFile.implement((path: string) => fs.readFileSync(path, 'utf-8')),
+];
 
 // Compile with platform
 const compiled = East.compile(myFunction, platform);
 ```
 
 East also supports `asyncPlatform` functions (which may be called by `AsyncFunctionType` user-defined functions), inserting `await` automatically as required.
-In the above, `readFile` could have be implented using `fs.promises.readFile` to take advantage of concurrency.
+In the above, `readFile` could have been implemented using `fs.promises.readFile` to take advantage of concurrency.
 
 ### Fluent Interface
 
@@ -154,15 +153,25 @@ Build expressions using chainable methods:
 ```typescript
 const myFunction = East.function([IntegerType], IntegerType, ($, x) => {
     // Arithmetic
-    const result = x.add(10n).multiply(2n).divide(3n);
+    const result = $.const(x.add(10n).multiply(2n));
 
     // Collections
-    const arr = $.let([1n, 2n, 3n]);
-    const doubled = arr.map(($, x, i) => x.multiply(2n));
-    const sum = doubled.sum();
+    const arr = $.const([1n, 2n, 3n]);
+    const doubled = $.const(arr.map(($, x, i) => x.multiply(2n)));
+    const sum = $.const(doubled.sum());
+
+    // Closures can capture variables from the enclosing scope
+    const addResult = $.const(East.function([IntegerType], IntegerType, ($, y) => {
+        $.return(y.add(result));
+    }));
 
-    $.return(sum);
+    $.return(addResult(sum));
 });
+
+// Compile and execute
+const compiled = East.compile(myFunction, []);
+compiled(5n);
+// 42n — result = (5+10)*2 = 30, sum of [2,4,6] = 12, addResult(12) = 12+30 = 42
 ```
 
 ### Serialization
@@ -175,28 +184,35 @@ All East data can be written and read in any of the following formats:
 
 Note that mutable aliasing _is_ preserved through serialization/deserialization.
 
-Function and closure values are not directly serializable (at least yet), but function definitions can be serialized as IR and transmitted across environments to compile and run on the other side:
+Function and closure definitions can be serialized as IR in the Beast2 binary format and transmitted across environments to compile and run on the other side:
 
 ```typescript
-// Convert to IR
-const ir = myFunction.toIR();
+import { East, IntegerType, Expr, encodeBeast2For, decodeBeast2For } from "@elaraai/east";
+
+const myFunction = East.function([IntegerType], IntegerType, ($, x) => {
+    $.return(x.add(1n));
+});
+
+// the type of the function (IntegerType -> IntegerType)
+const funcType = Expr.type(myFunction);
+
+// Compile the function (this attaches the IR)
+const compiled = East.compile(myFunction, []);
 
-// Serialize to JSON (handles bigints, NaN, Infinity correctly)
-const jsonData = ir.toJSON();
-const jsonString = JSON.stringify(jsonData);
+// Serialize the compiled function to Beast2 (binary format)
+const encode = encodeBeast2For(funcType);
+const bytes = encode(compiled);
 
-// Send over network, save to file, etc.
-// ...
+// Deserialize and recompile
+const decode = decodeBeast2For(funcType);
+const restored = decode(bytes);
 
-// Deserialize and compile
-const receivedData = JSON.parse(jsonString);
-const receivedIR = EastIR.fromJSON(receivedData);
-const compiled = receivedIR.compile(platform);
+restored(41n); // 42n
 ```
 
 ## Examples
 
-See the [USAGE.md](./USAGE.md) for more.
+See the [SKILL.md](./SKILL.md) for more.
 
 ## Development
 
@@ -222,58 +238,24 @@ Notably, these tests are hosted in East and allow one to validate the correctnes
 
 ### Release Process
 
-East uses automated releases via GitHub Actions. The process differs for stable and beta releases:
+`@elaraai/east` is published together with every other `@elaraai/*` npm package in the east-workspace monorepo under a single unified version. Releases are triggered manually via the `NPM Publish` GitHub Actions workflow at the repo root (`.github/workflows/npm-publish.yml`). There is no per-package release command — see the root [README.md](../../README.md#release-process) for details.
 
-#### Stable Releases
+## Claude Code plugin
 
-For stable releases (published to npm with `latest` tag):
+The East ecosystem also ships a [Claude Code](https://claude.com/claude-code) plugin — East language skills, example search, and preemptive diagnostics for East code — installed separately from the `elaraai` marketplace:
 
-```bash
-npm run release:patch    # 0.0.1 → 0.0.2
-npm run release:minor    # 0.0.1 → 0.1.0
-npm run release:major    # 0.0.1 → 1.0.0
+```text
+# Inside Claude Code
+/plugin marketplace add elaraai/east-workspace
+/plugin install east@elaraai
 ```
 
-These commands will:
-1. Bump the version in `package.json`
-2. Create a git commit with message `chore: bump version to X.Y.Z`
-3. Create a git tag `vX.Y.Z`
-4. Push the commit and tag to GitHub
-5. GitHub Actions automatically builds, tests, and publishes to npm with `latest` tag
-
-#### Beta Releases
-
-For beta/prerelease versions (published to npm with `beta` tag):
-
-```bash
-npm run release:prepatch      # 0.0.1 → 0.0.2-beta.0
-npm run release:preminor      # 0.0.1 → 0.1.0-beta.0
-npm run release:premajor      # 0.0.1 → 1.0.0-beta.0
-npm run release:prerelease    # 0.0.1-beta.0 → 0.0.1-beta.1
-```
-
-Beta releases follow the same automated process but are published to npm with the `beta` tag.
-
-#### Manual Version Bumping (Dry Run)
-
-To update the version without committing or tagging:
-
 ```bash
-npm run version:patch:dry
-npm run version:minor:dry
-npm run version:major:dry
-npm run version:prepatch:dry
-npm run version:preminor:dry
-npm run version:premajor:dry
-npm run version:prerelease:dry
+# From a terminal
+claude plugin marketplace add elaraai/east-workspace
+claude plugin install east@elaraai
 ```
 
-#### Requirements
-
-- **Automated Publishing**: Requires `NPM_TOKEN` secret configured in GitHub repository settings
-- **Pre-publish Checks**: All tests and linting must pass before publishing (enforced by `prepublishOnly` hook)
-- **Node Version**: Requires Node.js ≥22.0.0
-
 ## License
 
 This project is dual-licensed:
@@ -289,16 +271,59 @@ We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for deta
 
 **Note**: Contributors must sign our [CLA](CLA.md) before we can accept pull requests. This allows us to offer commercial licenses while keeping the project open source.
 
+### Ecosystem
+
+- **[East](https://github.com/elaraai/east-workspace/tree/main/libs/east)**: Statically typed, expression-based language with serializable IR. Run portable logic across TypeScript, Python, C, and other runtimes.
+  - [@elaraai/east](https://www.npmjs.com/package/@elaraai/east): Core language SDK with type system, expressions, and reference JS compiler
+
+- **[East Node](https://github.com/elaraai/east-workspace/tree/main/libs/east-node)**: Node.js platform functions for I/O, databases, and system operations.
+  - [@elaraai/east-node-std](https://www.npmjs.com/package/@elaraai/east-node-std): Console, FileSystem, Fetch, Crypto, Time, Path, Random
+  - [@elaraai/east-node-io](https://www.npmjs.com/package/@elaraai/east-node-io): SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
+  - [@elaraai/east-node-cli](https://www.npmjs.com/package/@elaraai/east-node-cli): CLI for running East IR programs in Node.js
+
+- **[East C](https://github.com/elaraai/east-workspace/tree/main/libs/east-c)**: C11 native runtime for executing East IR. Tarballed for `linux-x64` and `linux-arm64`, attached to each GitHub Release.
+  - `east-c`: Core runtime — type system, IR interpreter, 200+ builtins, serialization (Beast2, JSON, CSV, East text)
+  - `east-c-std`: Console, FileSystem, Fetch, Crypto, Time, Path, Random
+  - `east-c-cli`: CLI for running East IR programs natively
+
+- **[East Python](https://github.com/elaraai/east-workspace/tree/main/libs/east-py)**: Python runtime, standard platform, I/O, and data-science platform functions. Published to PyPI.
+  - [east-py](https://pypi.org/project/east-py/): Core Python runtime — type system, IR compiler, 212+ builtins, Cython-accelerated hot paths
+  - [east-py-std](https://pypi.org/project/east-py-std/): Console, FileSystem, Fetch, Crypto, Time, Path, Random
+  - [east-py-io](https://pypi.org/project/east-py-io/): SQLite, PostgreSQL, MySQL, MongoDB, Redis, S3, FTP, SFTP, XLSX, XML, compression
+  - [east-py-cli](https://pypi.org/project/east-py-cli/): CLI for running East IR programs in Python
+  - [east-py-datascience](https://pypi.org/project/east-py-datascience/) (PyPI) + [@elaraai/east-py-datascience](https://www.npmjs.com/package/@elaraai/east-py-datascience) (npm): Optimization (MADS, Optuna, ALNS, GoogleOR), ML (XGBoost, LightGBM, NGBoost, PyTorch, Lightning, GP), Bayesian inference (PyMC), explainability (SHAP), conformal prediction (MAPIE)
+
+- **[East UI](https://github.com/elaraai/east-workspace/tree/main/libs/east-ui)**: Typed UI component definitions and React renderer, plus VS Code preview.
+  - [@elaraai/east-ui](https://www.npmjs.com/package/@elaraai/east-ui): 50+ typed UI components for layouts, forms, charts, tables, dialogs
+  - [@elaraai/east-ui-components](https://www.npmjs.com/package/@elaraai/east-ui-components): React renderer with Chakra UI v3 styling
+  - [@elaraai/e3-ui](https://www.npmjs.com/package/@elaraai/e3-ui): e3 + UI bridge — Data bindings, `e3.ui()` task, manifest
+  - [@elaraai/e3-ui-components](https://www.npmjs.com/package/@elaraai/e3-ui-components): React Query hooks and preview components for the e3 API
+  - [east-ui-preview](https://marketplace.visualstudio.com/items?itemName=ElaraAI.east-ui-preview): VS Code extension for live East UI component preview
+
+- **[e3 — East Execution Engine](https://github.com/elaraai/east-workspace/tree/main/libs/e3)**: Durable execution engine for running East pipelines at scale. Git-like content-addressable storage, automatic memoization, reactive dataflow, real-time monitoring.
+  - [@elaraai/e3](https://www.npmjs.com/package/@elaraai/e3): SDK for authoring e3 packages with typed tasks and pipelines
+  - [@elaraai/e3-core](https://www.npmjs.com/package/@elaraai/e3-core): Object store, dataflow orchestrator, execution state
+  - [@elaraai/e3-types](https://www.npmjs.com/package/@elaraai/e3-types): Shared type definitions for e3 packages
+  - [@elaraai/e3-cli](https://www.npmjs.com/package/@elaraai/e3-cli): `e3 repo`, `e3 package`, `e3 workspace`, `e3 start`, `e3 watch`, `e3 logs` commands
+  - [@elaraai/e3-api-client](https://www.npmjs.com/package/@elaraai/e3-api-client): HTTP client for remote e3 repositories
+  - [@elaraai/e3-api-server](https://www.npmjs.com/package/@elaraai/e3-api-server): REST API server for e3 repositories
+  - [@elaraai/e3-api-tests](https://www.npmjs.com/package/@elaraai/e3-api-tests): Shared API compliance test suites
+
 ## Links
 
 - **Website**: [https://elaraai.com/](https://elaraai.com/)
-- **Repository**: [https://github.com/elaraai/east](https://github.com/elaraai/east)
-- **Issues**: [https://github.com/elaraai/east/issues](https://github.com/elaraai/east/issues)
+- **Repository**: [https://github.com/elaraai/east-workspace/tree/main/libs/east](https://github.com/elaraai/east-workspace/tree/main/libs/east)
+- **Issues**: [https://github.com/elaraai/east-workspace/issues](https://github.com/elaraai/east-workspace/issues)
 - **Email**: support@elara.ai
 
 ## About Elara
 
-East is developed by [Elara AI Pty Ltd](https://elaraai.com/), an AI-powered platform that creates economic digital twins of businesses that optimize performance. Elara combines business objectives, decisions and data to help organizations make data-driven decisions across work management, purchasing, customer engagement, and investment planning. East powers the computational layer of Elara solutions, enabling the expression of complex business logic and data in a simple, type-safe and portable language.
+East is developed by [Elara AI Pty Ltd](https://elaraai.com/), an AI-powered platform that creates economic digital twins of businesses that optimize performance. Elara combines business objectives, decisions and data to help organizations make data-driven decisions across operations, purchasing, sales and customer engagement, and project and investment planning. East powers the computational layer of Elara solutions, enabling the expression of complex business logic and data in a simple, type-safe and portable language.
+
+---
+
+*Developed by [Elara AI Pty Ltd](https://elaraai.com/).*
 
 ---
 
+*Developed by [Elara AI Pty Ltd](https://elaraai.com/)*

package/dist/src/analyze.d.ts

@@ -37,6 +37,9 @@ export type PlatformDefinition = {
     inputs: EastTypeValue[];
     output: EastTypeValue;
     type: 'sync' | 'async';
+    type_parameters?: string[];
+    inputsFn?: (...typeParams: EastTypeValue[]) => EastTypeValue[];
+    outputsFn?: (...typeParams: EastTypeValue[]) => EastTypeValue;
 };
 export type AnalyzedIR<T extends IR = IR> = T & {
     value: {

package/dist/src/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/analyze.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,KAAK,EAA+B,EAAE,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,mBAAmB,CAAC;AAOxE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG;IAAE,KAAK,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAAC;AAGhF;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,IAAI,EAAE,aAAa,CAAC;IAEpB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IAEjB,yFAAyF;IACzF,SAAS,EAAE,EAAE,CAAC;IAEd,uFAAuF;IACvF,QAAQ,EAAE,OAAO,CAAC;CAYnB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,EAAE,EACpC,EAAE,EAAE,CAAC,EACL,WAAW,EAAE,kBAAkB,EAAE,EACjC,GAAG,GAAE,eAAoB,GACxB,UAAU,CAAC,CAAC,CAAC,CAmiDf"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/analyze.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,KAAK,EAA+B,EAAE,EAAE,MAAM,SAAS,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAmB,MAAM,mBAAmB,CAAC;AAOxE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAEvB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,CAAC;IAC/D,SAAS,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,aAAa,EAAE,KAAK,aAAa,CAAC;CAC/D,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG;IAAE,KAAK,EAAE;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,CAAC;AAGhF;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,IAAI,EAAE,aAAa,CAAC;IAEpB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IAEjB,yFAAyF;IACzF,SAAS,EAAE,EAAE,CAAC;IAEd,uFAAuF;IACvF,QAAQ,EAAE,OAAO,CAAC;CAYnB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,EAAE,EACpC,EAAE,EAAE,CAAC,EACL,WAAW,EAAE,kBAAkB,EAAE,EACjC,GAAG,GAAE,eAAoB,GACxB,UAAU,CAAC,CAAC,CAAC,CA4qDf"}