@elaraai/e3-core 0.0.1-alpha.2

package/LICENSE.md

@@ -0,0 +1,50 @@
+# Business Source License 1.1
+
+Copyright (c) 2025 Elara AI Pty Ltd
+
+## License
+
+**Licensor:** Elara AI Pty Ltd
+
+**Licensed Work:** @elaraai/e3-core
+
+**Change Date:** Four years from the date of each release
+
+**Change License:** AGPL-3.0
+
+## Terms
+
+The Licensed Work is provided under the terms of the Business Source License 1.1 as detailed below.
+
+### Grant of Rights
+
+The Licensor grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work.
+
+### Production Use Limitation
+
+**"Production Use"** means any use by or on behalf of a for-profit entity, other than for evaluation, testing, or development purposes.
+
+Production Use requires a separate commercial license from the Licensor.
+
+### Change Date
+
+On the Change Date (four years after each release), the Licensed Work will be made available under the Change License (AGPL-3.0).
+
+### No Warranty
+
+THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. THE LICENSOR DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+## Commercial Licensing
+
+To obtain a commercial license for Production Use, contact:
+
+**Email:** support@elara.ai
+**Website:** https://elaraai.com
+
+## Governing Law
+
+This license is governed by the laws of New South Wales, Australia.
+
+---
+
+*Elara AI Pty Ltd*

package/README.md

@@ -0,0 +1,103 @@
+# @elaraai/e3-core
+
+Core library for e3 repository operations, similar to libgit2 for git.
+
+## Installation
+
+```bash
+npm install @elaraai/e3-core
+```
+
+## Overview
+
+Pure business logic with no UI dependencies. Use this to build custom tools, integrations, or alternative interfaces on top of e3.
+
+## API
+
+### Repository
+
+```typescript
+import { initRepository, findRepository, getRepository } from '@elaraai/e3-core';
+
+initRepository('/path/to/project');
+const repoPath = findRepository();  // Searches cwd and parents
+```
+
+### Objects
+
+```typescript
+import { storeObject, loadObject, computeTaskId } from '@elaraai/e3-core';
+
+const hash = await storeObject(repoPath, data, '.beast2');
+const data = await loadObject(repoPath, hash, '.beast2');
+const taskId = computeTaskId(irHash, argsHashes);
+```
+
+### Commits
+
+```typescript
+import { createNewTaskCommit, createTaskDoneCommit, loadCommit } from '@elaraai/e3-core';
+
+const commitHash = await createNewTaskCommit(repoPath, taskId, irHash, argsHashes, 'node', null);
+const commit = await loadCommit(repoPath, commitHash);
+```
+
+### Tasks
+
+```typescript
+import { updateTaskState, getTaskState, listTasks } from '@elaraai/e3-core';
+
+await updateTaskState(repoPath, taskId, commitHash);
+const commit = await getTaskState(repoPath, taskId);
+const tasks = await listTasks(repoPath);
+```
+
+### Refs
+
+```typescript
+import { setTaskRef, deleteTaskRef, listTaskRefs, resolveToTaskId } from '@elaraai/e3-core';
+
+await setTaskRef(repoPath, 'my-task', taskId);
+const taskId = await resolveToTaskId(repoPath, 'my-task');
+```
+## License
+
+BSL 1.1. See [LICENSE.md](./LICENSE.md).
+
+### Ecosystem
+
+- **[East Node](https://github.com/elaraai/east-node)**: Node.js platform functions for I/O, databases, and system operations. Connect East programs to filesystems, SQL/NoSQL databases, cloud storage, and network services.
+  - [@elaraai/east-node-std](https://www.npmjs.com/package/@elaraai/east-node-std): Filesystem, console, HTTP fetch, crypto, random distributions, timestamps
+  - [@elaraai/east-node-io](https://www.npmjs.com/package/@elaraai/east-node-io): SQLite, PostgreSQL, MySQL, MongoDB, S3, FTP, SFTP
+  - [@elaraai/east-node-cli](https://www.npmjs.com/package/@elaraai/east-node-cli): CLI for running East IR programs in Node.js
+
+- **[East Python](https://github.com/elaraai/east-py)**: Python runtime and platform functions for data science and machine learning. Execute East programs with access to optimization solvers, gradient boosting, neural networks, and model explainability.
+  - [@elaraai/east-py-datascience](https://www.npmjs.com/package/@elaraai/east-py-datascience): TypeScript types for optimization, gradient boosting, neural networks, explainability
+
+- **[East UI](https://github.com/elaraai/east-ui)**: East types and expressions for building dashboards and interactive layouts. Define UIs as data structures that render consistently across React, web, and other environments.
+  - [@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 styling
+
+- **[e3 - East Execution Engine](https://github.com/elaraai/e3)**: Durable execution engine for running East pipelines at scale. Features Git-like content-addressable storage, automatic memoization, task queuing, and 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): Git-like object store, task queue, result caching
+  - [@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 init`, `e3 run`, `e3 logs` commands for managing and monitoring tasks
+  - [@elaraai/e3-api-client](https://www.npmjs.com/package/@elaraai/e3-api-client): HTTP client for remote e3 servers
+  - [@elaraai/e3-api-server](https://www.npmjs.com/package/@elaraai/e3-api-server): REST API server for e3 repositories
+
+## Links
+
+- [East Language](https://github.com/elaraai/east)
+- [East Python Runtime](https://github.com/elaraai/east-py)
+- [Elara AI](https://elaraai.com/)
+- [Issues](https://github.com/elaraai/e3/issues)
+- 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 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/)*

package/dist/src/dataflow.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type WorkspaceLockHandle } from './workspaceLock.js';
+/**
+ * Result of executing a single task in the dataflow.
+ */
+export interface TaskExecutionResult {
+    /** Task name */
+    name: string;
+    /** Whether the task was cached */
+    cached: boolean;
+    /** Final state */
+    state: 'success' | 'failed' | 'error' | 'skipped';
+    /** Error message if state is 'error' */
+    error?: string;
+    /** Exit code if state is 'failed' */
+    exitCode?: number;
+    /** Duration in milliseconds */
+    duration: number;
+}
+/**
+ * Result of a dataflow execution.
+ */
+export interface DataflowResult {
+    /** Overall success - true if all tasks completed successfully */
+    success: boolean;
+    /** Number of tasks executed (not from cache) */
+    executed: number;
+    /** Number of tasks served from cache */
+    cached: number;
+    /** Number of tasks that failed */
+    failed: number;
+    /** Number of tasks skipped due to upstream failure */
+    skipped: number;
+    /** Per-task results */
+    tasks: TaskExecutionResult[];
+    /** Total duration in milliseconds */
+    duration: number;
+}
+/**
+ * Options for dataflow execution.
+ */
+export interface DataflowOptions {
+    /** Maximum concurrent task executions (default: 4) */
+    concurrency?: number;
+    /** Force re-execution even if cached (default: false) */
+    force?: boolean;
+    /** Filter to run only specific task(s) by exact name */
+    filter?: string;
+    /**
+     * External workspace lock to use. If provided, the caller is responsible
+     * for releasing the lock after execution. If not provided, dataflowExecute
+     * will acquire and release a lock internally.
+     *
+     * Use an external lock when you need to hold the lock across multiple
+     * operations (e.g., API server that cancels and restarts dataflow on writes).
+     */
+    lock?: WorkspaceLockHandle;
+    /**
+     * AbortSignal for cancellation. When aborted:
+     * - No new tasks will be started
+     * - Running tasks will be killed (SIGTERM, then SIGKILL)
+     * - DataflowAbortedError will be thrown with partial results
+     */
+    signal?: AbortSignal;
+    /** Callback when a task starts */
+    onTaskStart?: (name: string) => void;
+    /** Callback when a task completes */
+    onTaskComplete?: (result: TaskExecutionResult) => void;
+    /** Callback for task stdout */
+    onStdout?: (taskName: string, data: string) => void;
+    /** Callback for task stderr */
+    onStderr?: (taskName: string, data: string) => void;
+}
+/**
+ * Execute all tasks in a workspace according to the dependency graph.
+ *
+ * Tasks are executed in parallel where dependencies allow, respecting
+ * the concurrency limit. On failure, no new tasks are launched but
+ * running tasks are allowed to complete.
+ *
+ * Acquires an exclusive lock on the workspace for the duration of execution
+ * to prevent concurrent modifications. If options.lock is provided, uses that
+ * lock instead (caller is responsible for releasing it).
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @param options - Execution options
+ * @returns Result of the dataflow execution
+ * @throws {WorkspaceLockError} If workspace is locked by another process
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceNotDeployedError} If workspace has no package deployed
+ * @throws {TaskNotFoundError} If filter specifies a task that doesn't exist
+ * @throws {DataflowError} If execution fails for other reasons
+ */
+export declare function dataflowExecute(repoPath: string, ws: string, options?: DataflowOptions): Promise<DataflowResult>;
+/**
+ * Start dataflow execution in the background (non-blocking).
+ *
+ * Returns a promise immediately without awaiting execution. The lock is
+ * released automatically when execution completes.
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @param options - Execution options (lock must be provided)
+ * @returns Promise that resolves when execution completes
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceNotDeployedError} If workspace has no package deployed
+ * @throws {TaskNotFoundError} If filter specifies a task that doesn't exist
+ * @throws {DataflowError} If execution fails for other reasons
+ */
+export declare function dataflowStart(repoPath: string, ws: string, options: DataflowOptions & {
+    lock: WorkspaceLockHandle;
+}): Promise<DataflowResult>;
+/**
+ * Get the dependency graph for a workspace (for visualization/debugging).
+ *
+ * @param repoPath - Path to .e3 repository
+ * @param ws - Workspace name
+ * @returns Graph information
+ * @throws {WorkspaceNotFoundError} If workspace doesn't exist
+ * @throws {WorkspaceNotDeployedError} If workspace has no package deployed
+ * @throws {DataflowError} If graph building fails for other reasons
+ */
+export declare function dataflowGetGraph(repoPath: string, ws: string): Promise<{
+    tasks: Array<{
+        name: string;
+        hash: string;
+        inputs: string[];
+        output: string;
+        dependsOn: string[];
+    }>;
+}>;
+//# sourceMappingURL=dataflow.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dataflow.d.ts","sourceRoot":"","sources":["../../src/dataflow.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAmDH,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AA2E5B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,kBAAkB;IAClB,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;IAClD,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kCAAkC;IAClC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,qCAAqC;IACrC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACvD,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAqHD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAazB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,GACvD,OAAO,CAAC,cAAc,CAAC,CAGzB;AAmVD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC;IACT,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC,CAAC;CACJ,CAAC,CA0CD"}