@elaraai/east 0.0.1-beta.0

package/README.md

@@ -0,0 +1,276 @@
+# East
+
+**East** is a statically typed, expression-based programming language embedded in TypeScript. Designed for the [Elara](https://elaraai.com/) platform, East enables you to write portable logic once and execute it across multiple environments (JavaScript, Julia, Python, and more), leveraging each language's native performance characteristics and ecosystem.
+
+## 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/MCP Friendly**: Designed for code generation with clear, composable TypeScript API
+- **📦 Minimal Dependencies**: Single runtime dependency (sorted-btree for efficient collections)
+- **🛡️ Total Ordering**: All types (even floats with NaN) have defined comparisons
+- **🔄 Serializable**: Functions and data can be transmitted as IR
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @elaraai/east
+```
+
+### Basic Example
+
+
+```typescript
+import { East, IntegerType, ArrayType, StructType, StringType, DictType, NullType } from "@elaraai/east";
+
+// Platform function for logging
+const log = East.platform("log", [StringType], NullType);
+
+const platform = [
+    log.implement(console.log),
+];
+
+// Define sale data type
+const SaleType = StructType({
+    product: StringType,
+    quantity: IntegerType,
+    price: IntegerType
+});
+
+// Calculate revenue per product from sales data
+const calculateRevenue = East.function(
+    [ArrayType(SaleType)],
+    DictType(StringType, IntegerType),
+    ($, sales) => {
+        // Group sales by product and sum revenue (quantity × price)
+        const revenueByProduct = sales.groupSum(
+            // Group by product name
+            ($, sale) => sale.product,          
+            // Sum quantity × price    
+            ($, sale) => sale.quantity.multiply(sale.price)  
+        );
+
+        // Log revenue for each product
+         $(log(East.str`Total Revenue: ${revenueByProduct.sum()}`));
+
+        $.return(revenueByProduct);
+    }
+);
+
+// Compile and execute
+const compiled = East.compile(calculateRevenue, platform);
+
+const sales = [
+    { product: "Widget", quantity: 10n, price: 50n },
+    { product: "Gadget", quantity: 5n, price: 100n },
+    { product: "Widget", quantity: 3n, price: 50n }
+];
+
+const result = compiled(sales);
+// Result: Map { "Widget" => 650n, "Gadget" => 500n }
+// Logs: "Gadget: $500" and "Widget: $650"
+```
+
+## Type System
+
+East supports a rich type system optimized for business logic and data processing:
+
+| Type | ValueTypeOf<Type> | Mutability | Description |
+|------|-----------------|------------|-------------|
+| **Primitive Types** | | | |
+| `NullType` | `null` | Immutable | Unit type (single value) |
+| `BooleanType` | `boolean` | Immutable | True or false |
+| `IntegerType` | `bigint` | Immutable | 64-bit signed integers |
+| `FloatType` | `number` | Immutable | IEEE 754 double-precision |
+| `StringType` | `string` | Immutable | UTF-8 text |
+| `DateTimeType` | `Date` | Immutable | UTC timestamp with millisecond precision |
+| `BlobType` | `Uint8Array` | Immutable | Binary data |
+| **Compound Types** | | | |
+| `ArrayType<T>` | `ValueTypeOf<T>[]` | **Mutable** | Ordered collection |
+| `SetType<K>` | `Set<ValueTypeOf<K>>` | **Mutable** | Sorted set |
+| `DictType<K, V>` | `Map<ValueTypeOf<K>, ValueTypeOf<V>>` | **Mutable** | Sorted dictionary |
+| `StructType<Fields>` | `{...}` | Immutable | Product type (records) |
+| `VariantType<Cases>` | `variant` | Immutable | Sum type (tagged unions) |
+| `RecursiveType<T>` | `ValueTypeOf<T>` | Immutable | Recursive references for trees, DAGs, and circular structures |
+| **Function Type** | | | |
+| `FunctionType<I, O>` | Function | Immutable | First-class functions |
+
+## Documentation
+
+- **[USAGE.md](USAGE.md)** - Comprehensive developer guide with API 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
+
+## Key Concepts
+
+### Platform Functions
+
+East code runs in a controlled environment. You define **platform functions** that your East code can call:
+
+```typescript
+// Define platform function helper
+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')
+};
+
+// Compile with platform
+const compiled = East.compile(myFunction, platform);
+```
+
+### Fluent Interface
+
+Build expressions using chainable methods:
+
+```typescript
+const myFunction = East.function([IntegerType], IntegerType, ($, x) => {
+    // Arithmetic
+    const result = x.add(10n).multiply(2n).divide(3n);
+
+    // Collections
+    const arr = $.let([1n, 2n, 3n]);
+    const doubled = arr.map(($, x, i) => x.multiply(2n));
+    const sum = doubled.sum();
+
+    $.return(sum);
+});
+```
+
+### Serialization
+
+Functions can be serialized as IR and transmitted across environments:
+
+```typescript
+// Convert to IR
+const ir = myFunction.toIR();
+
+// Serialize to JSON (handles bigints, NaN, Infinity correctly)
+const jsonData = ir.toJSON();
+const jsonString = JSON.stringify(jsonData);
+
+// Send over network, save to file, etc.
+// ...
+
+// Deserialize and compile
+const receivedData = JSON.parse(jsonString);
+const receivedIR = EastIR.fromJSON(receivedData);
+const compiled = receivedIR.compile(platform);
+```
+
+## Examples
+
+See the [examples](./examples) directory for more:
+
+- **[example.ts](./examples/example.ts)** - Basic examples demonstrating core features
+
+## Development
+
+### Building
+
+```bash
+npm run build       # Compile TypeScript to JavaScript
+npm run test        # Run test suite (requires build first)
+npm run lint        # Check code quality with ESLint
+npm run example     # Run the basic example
+```
+
+### Testing
+
+East has a comprehensive test suite with tests covering:
+
+- Type system operations
+- Serialization formats (BEAST v1/v2, JSON, EAST text format)
+- Collections and functional operations
+- Error handling and edge cases
+
+### Release Process
+
+East uses automated releases via GitHub Actions. The process differs for stable and beta releases:
+
+#### Stable Releases
+
+For stable releases (published to npm with `latest` tag):
+
+```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
+```
+
+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
+```
+
+#### 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:
+
+- **Open Source**: [AGPL-3.0](LICENSE.md) - Free for open source use with source disclosure requirements
+- **Commercial**: Available for proprietary use - contact support@elara.ai
+
+See [LICENSE.md](LICENSE.md) for full details.
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+**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.
+
+## 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)
+- **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.
+
+---
+

package/dist/src/analyze.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Analysis and validation of IR for JavaScript backend compilation.
+ *
+ * This module provides backend-specific enrichment of universal IR,
+ * computing metadata needed for efficient JavaScript closure compilation.
+ * Different backends (Julia, Python, etc.) would have their own analysis modules.
+ */
+import type { IR } from "./ir.js";
+import type { EastTypeValue } from "./type_of_type.js";
+/**
+ * Platform definition for JavaScript backend.
+ *
+ * Maps platform function names to their implementations and async metadata.
+ * Different JavaScript execution environments may provide different platforms
+ * with the same functions but different async characteristics.
+ *
+ * Types are stored as EastTypeValue (IR representation) rather than EastType
+ * (front-end representation) to avoid repeated conversion during analysis.
+ *
+ * @example
+ * ```ts
+ * const log = East.platform("log", [StringType], NullType);
+ * const readFile = East.platform("readFile", [StringType], StringType);
+ *
+ * const platform = [
+ *   log.implement(console.log),
+ *   readFile.implementAsync(fs.promises.readFile),
+ * ];
+ * ```
+ */
+export type PlatformDefinition = {
+    name: string;
+    inputs: EastTypeValue[];
+    output: EastTypeValue;
+    type: 'sync' | 'async';
+};
+export type AnalyzedIR<T extends IR = IR> = T & {
+    value: {
+        isAsync: boolean;
+    };
+};
+/**
+ * Variable metadata tracked during analysis.
+ *
+ * Tracks type information and other properties needed for optimization
+ * and code generation.
+ */
+export interface VariableMetadata {
+    /** The East type of this variable */
+    type: EastTypeValue;
+    /** Whether this variable can be mutated (let vs const) */
+    mutable: boolean;
+    /** The IR node that defined this variable (VariableIR from Let or Function parameter) */
+    definedBy: IR;
+    /** Whether this variable is captured by a nested function (mutated during analysis) */
+    captured: boolean;
+}
+/**
+ * Variable context mapping names to their metadata.
+ *
+ * Used during analysis to track variable types and properties.
+ */
+export type VariableContext = Record<string, VariableMetadata>;
+/**
+ * Analyze IR tree and produce enriched IR for JavaScript backend.
+ *
+ * This function:
+ * - Validates the IR (type checking, variable scope, etc.)
+ * - Computes which nodes require async compilation
+ * - Returns enriched IR with metadata populated (isAsync, etc.)
+ *
+ * @param ir - The IR tree to analyze
+ * @param platformDef - Platform function definitions with async metadata
+ * @param ctx - Variable context mapping variable names to their metadata
+ * @returns Enriched IR with metadata fields populated
+ * @throws {Error} If IR is invalid (type errors, undefined variables, etc.)
+ *
+ * @example
+ * ```ts
+ * const ir = // ... parsed East program
+ * const platform = [
+ *   log.implement(console.log),
+ *   fetch.implementAsync(fetch)
+ * ];
+ *
+ * const enrichedIR = analyzeIR(ir, platform, {});
+ * const compiled = compile_internal(enrichedIR, {}, platform);
+ * ```
+ */
+export declare function analyzeIR(ir: IR, platformDef: PlatformDefinition[], ctx?: VariableContext): AnalyzedIR;
+//# sourceMappingURL=analyze.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/analyze.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AAEH,OAAO,KAAK,EAAc,EAAE,EAAE,MAAM,SAAS,CAAC;AAE9C,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,CACvB,EAAE,EAAE,EAAE,EACN,WAAW,EAAE,kBAAkB,EAAE,EACjC,GAAG,GAAE,eAAoB,GACxB,UAAU,CAo6CZ"}