@elaraai/e3-types 0.0.1-beta.0 → 0.0.2-beta.1

package/README.md

@@ -18,16 +18,45 @@ npm install @elaraai/e3-types
 - **Dataflow** - Dataflow definitions
 - **Runner** - Runner configuration
 
-## Related Repos
 
-- **[east](https://github.com/elaraai/east)** - East language core
-- **[east-node](https://github.com/elaraai/east-node)** - Node.js runtime and platform functions
-- **[east-py](https://github.com/elaraai/east-py)** - Python runtime and data science
+## License
+
+Dual AGPL-3.0 / Commercial. 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
 
-e3 is developed by [Elara AI](https://elaraai.com/), an AI-powered platform that creates economic digital twins of businesses. e3 powers the execution layer of Elara solutions, enabling durable and efficient execution of East programs across multiple runtimes.
+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.
 
-## License
+---
 
-Dual AGPL-3.0 / Commercial. See [LICENSE.md](./LICENSE.md).
+*Developed by [Elara AI Pty Ltd](https://elaraai.com/)*

package/dist/src/index.d.ts

@@ -22,7 +22,7 @@
  */
 export { DataRefType, type DataRef, unassignedRef, nullRef, DataTreeType, } from './dataset.js';
 export { TaskObjectType, type TaskObject, } from './task.js';
-export { StructureType, type Structure, PathSegmentType, type PathSegment, TreePathType, type TreePath, type ParsePathResult, treePath, pathToString, parsePath, DatasetSchemaType, type DatasetSchema, } from './structure.js';
+export { StructureType, type Structure, PathSegmentType, type PathSegment, TreePathType, type TreePath, type ParsePathResult, type ParseDatasetPathResult, type ParsePackageRefResult, treePath, pathToString, parsePath, parseDatasetPath, parsePackageRef, urlPathToTreePath, DatasetSchemaType, type DatasetSchema, } from './structure.js';
 export { PackageDataType, type PackageData, PackageObjectType, type PackageObject, PackageDatasetsType, type PackageDatasets, } from './package.js';
 export { WorkspaceStateType, type WorkspaceState, } from './workspace.js';
 export { ExecutionStatusType, type ExecutionStatus, } from './execution.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EACL,WAAW,EACX,KAAK,OAAO,EACZ,aAAa,EACb,OAAO,EACP,YAAY,GACb,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,cAAc,EACd,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,aAAa,EACb,KAAK,SAAS,EACd,eAAe,EACf,KAAK,WAAW,EAChB,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,QAAQ,EACR,YAAY,EACZ,SAAS,EAET,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,aAAa,EAElB,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EACL,WAAW,EACX,KAAK,OAAO,EACZ,aAAa,EACb,OAAO,EACP,YAAY,GACb,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,cAAc,EACd,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,aAAa,EACb,KAAK,SAAS,EACd,eAAe,EACf,KAAK,WAAW,EAChB,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EAEjB,iBAAiB,EACjB,KAAK,aAAa,GACnB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,iBAAiB,EACjB,KAAK,aAAa,EAElB,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,kBAAkB,EAClB,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,gBAAgB,CAAC"}

package/dist/src/index.js

@@ -25,7 +25,7 @@ export { DataRefType, unassignedRef, nullRef, DataTreeType, } from './dataset.js
 // Task definitions
 export { TaskObjectType, } from './task.js';
 // Data structure and paths
-export { StructureType, PathSegmentType, TreePathType, treePath, pathToString, parsePath, 
+export { StructureType, PathSegmentType, TreePathType, treePath, pathToString, parsePath, parseDatasetPath, parsePackageRef, urlPathToTreePath, 
 // Backwards compatibility
 DatasetSchemaType, } from './structure.js';
 // Package objects

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,4BAA4B;AAC5B,OAAO,EACL,WAAW,EAEX,aAAa,EACb,OAAO,EACP,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,mBAAmB;AACnB,OAAO,EACL,cAAc,GAEf,MAAM,WAAW,CAAC;AAEnB,2BAA2B;AAC3B,OAAO,EACL,aAAa,EAEb,eAAe,EAEf,YAAY,EAGZ,QAAQ,EACR,YAAY,EACZ,SAAS;AACT,0BAA0B;AAC1B,iBAAiB,GAElB,MAAM,gBAAgB,CAAC;AAExB,kBAAkB;AAClB,OAAO,EACL,eAAe,EAEf,iBAAiB;AAEjB,0BAA0B;AAC1B,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AAEtB,kBAAkB;AAClB,OAAO,EACL,kBAAkB,GAEnB,MAAM,gBAAgB,CAAC;AAExB,mBAAmB;AACnB,OAAO,EACL,mBAAmB,GAEpB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AAEH,4BAA4B;AAC5B,OAAO,EACL,WAAW,EAEX,aAAa,EACb,OAAO,EACP,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,mBAAmB;AACnB,OAAO,EACL,cAAc,GAEf,MAAM,WAAW,CAAC;AAEnB,2BAA2B;AAC3B,OAAO,EACL,aAAa,EAEb,eAAe,EAEf,YAAY,EAKZ,QAAQ,EACR,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,eAAe,EACf,iBAAiB;AACjB,0BAA0B;AAC1B,iBAAiB,GAElB,MAAM,gBAAgB,CAAC;AAExB,kBAAkB;AAClB,OAAO,EACL,eAAe,EAEf,iBAAiB;AAEjB,0BAA0B;AAC1B,mBAAmB,GAEpB,MAAM,cAAc,CAAC;AAEtB,kBAAkB;AAClB,OAAO,EACL,kBAAkB,GAEnB,MAAM,gBAAgB,CAAC;AAExB,mBAAmB;AACnB,OAAO,EACL,mBAAmB,GAEpB,MAAM,gBAAgB,CAAC"}

package/dist/src/structure.d.ts

@@ -251,4 +251,89 @@ export declare function parsePath(pathStr: string, structure: Structure): ParseP
  * ```
  */
 export declare function treePath(structure: Structure, ...fields: string[]): ParsePathResult;
+/**
+ * Result of parsing a dataset path specification.
+ */
+export interface ParseDatasetPathResult {
+    /** Workspace name */
+    ws: string;
+    /** Path within the workspace */
+    path: TreePath;
+}
+/**
+ * Parse workspace.path.to.dataset syntax into workspace name and TreePath.
+ *
+ * This is a lenient parser that does not validate against a structure.
+ * Use this for parsing user input where the structure is not yet known.
+ *
+ * @param pathSpec - Path specification in dot notation (e.g., "production.inputs.sales")
+ * @returns Workspace name and path segments
+ *
+ * @throws {Error} If path is empty or has unclosed backticks
+ *
+ * @example
+ * ```ts
+ * parseDatasetPath("production")
+ * // { ws: "production", path: [] }
+ *
+ * parseDatasetPath("production.inputs.sales")
+ * // { ws: "production", path: [field("inputs"), field("sales")] }
+ *
+ * // For field names with special characters, use backticks:
+ * parseDatasetPath("production.`my field`")
+ * // { ws: "production", path: [field("my field")] }
+ * ```
+ */
+export declare function parseDatasetPath(pathSpec: string): ParseDatasetPathResult;
+/**
+ * Result of parsing a package reference.
+ */
+export interface ParsePackageRefResult {
+    /** Package name */
+    name: string;
+    /** Version string, or undefined if not specified */
+    version?: string;
+}
+/**
+ * Parse a package reference like "name" or "name@version".
+ *
+ * @param ref - Package reference string
+ * @returns Package name and optional version
+ *
+ * @example
+ * ```ts
+ * parsePackageRef("my-package")
+ * // { name: "my-package", version: undefined }
+ *
+ * parsePackageRef("my-package@1.0.0")
+ * // { name: "my-package", version: "1.0.0" }
+ *
+ * // Scoped packages work too:
+ * parsePackageRef("@scope/package@2.0.0")
+ * // { name: "@scope/package", version: "2.0.0" }
+ * ```
+ */
+export declare function parsePackageRef(ref: string): ParsePackageRefResult;
+/**
+ * Convert URL path segments to a TreePath.
+ *
+ * Takes slash-separated, URL-encoded path segments and converts them to
+ * a TreePath of field variants.
+ *
+ * @param urlPath - URL path string (e.g., "inputs/sales/data" or "/inputs/sales/data")
+ * @returns TreePath of field segments
+ *
+ * @example
+ * ```ts
+ * urlPathToTreePath("inputs/sales/data")
+ * // [field("inputs"), field("sales"), field("data")]
+ *
+ * urlPathToTreePath("inputs/my%20field")
+ * // [field("inputs"), field("my field")]
+ *
+ * urlPathToTreePath("")
+ * // []
+ * ```
+ */
+export declare function urlPathToTreePath(urlPath: string): TreePath;
 //# sourceMappingURL=structure.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../../src/structure.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAA0C,MAAM,eAAe,CAAC;AAEjJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,aAAa;IACxB,iEAAiE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEjE,8DAA8D;;GAE7D,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC;AAEjD,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC;AAG1D,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB;IAX5B,iEAAiE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEjE,8DAA8D;;GASlB,CAAC;AAC/C,wCAAwC;AACxC,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAC9C,wCAAwC;AACxC,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC;AAEtC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe;IAC1B,kCAAkC;;EAKlC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY;IA1BvB,kCAAkC;;GA0BkB,CAAC;AACvD,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAE/C,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAQnD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,yCAAyC;IACzC,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,eAAe,CAgEhF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,eAAe,CAEnF"}
+{"version":3,"file":"structure.d.ts","sourceRoot":"","sources":["../../src/structure.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,WAAW,EAA0C,MAAM,eAAe,CAAC;AAEjJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,aAAa;IACxB,iEAAiE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEjE,8DAA8D;;GAE7D,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC;AAEjD,MAAM,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,aAAa,CAAC,CAAC;AAG1D,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB;IAX5B,iEAAiE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEjE,8DAA8D;;GASlB,CAAC;AAC/C,wCAAwC;AACxC,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAC9C,wCAAwC;AACxC,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC;AAEtC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe;IAC1B,kCAAkC;;EAKlC,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY;IA1BvB,kCAAkC;;GA0BkB,CAAC;AACvD,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC;AAE/C,MAAM,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAQnD;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,yCAAyC;IACzC,SAAS,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,eAAe,CAgEhF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,GAAG,eAAe,CAEnF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAWzE;AAqCD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAUlE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAG3D"}

package/dist/src/structure.js

@@ -233,4 +233,123 @@ export function parsePath(pathStr, structure) {
 export function treePath(structure, ...fields) {
     return parsePath('.' + fields.map(printIdentifier).join('.'), structure);
 }
+/**
+ * Parse workspace.path.to.dataset syntax into workspace name and TreePath.
+ *
+ * This is a lenient parser that does not validate against a structure.
+ * Use this for parsing user input where the structure is not yet known.
+ *
+ * @param pathSpec - Path specification in dot notation (e.g., "production.inputs.sales")
+ * @returns Workspace name and path segments
+ *
+ * @throws {Error} If path is empty or has unclosed backticks
+ *
+ * @example
+ * ```ts
+ * parseDatasetPath("production")
+ * // { ws: "production", path: [] }
+ *
+ * parseDatasetPath("production.inputs.sales")
+ * // { ws: "production", path: [field("inputs"), field("sales")] }
+ *
+ * // For field names with special characters, use backticks:
+ * parseDatasetPath("production.`my field`")
+ * // { ws: "production", path: [field("my field")] }
+ * ```
+ */
+export function parseDatasetPath(pathSpec) {
+    const segments = parsePathSegments(pathSpec);
+    if (segments.length === 0) {
+        throw new Error('Path cannot be empty');
+    }
+    const ws = segments[0];
+    const path = segments.slice(1).map((s) => variant('field', s));
+    return { ws, path };
+}
+/**
+ * Parse dot-separated path into segments, handling backtick-quoted identifiers.
+ * @internal
+ */
+function parsePathSegments(pathSpec) {
+    const segments = [];
+    let current = '';
+    let inBackticks = false;
+    for (let i = 0; i < pathSpec.length; i++) {
+        const char = pathSpec[i];
+        if (char === '`') {
+            inBackticks = !inBackticks;
+        }
+        else if (char === '.' && !inBackticks) {
+            if (current.length > 0) {
+                segments.push(current);
+                current = '';
+            }
+        }
+        else {
+            current += char;
+        }
+    }
+    if (current.length > 0) {
+        segments.push(current);
+    }
+    if (inBackticks) {
+        throw new Error('Unclosed backtick in path');
+    }
+    return segments;
+}
+/**
+ * Parse a package reference like "name" or "name@version".
+ *
+ * @param ref - Package reference string
+ * @returns Package name and optional version
+ *
+ * @example
+ * ```ts
+ * parsePackageRef("my-package")
+ * // { name: "my-package", version: undefined }
+ *
+ * parsePackageRef("my-package@1.0.0")
+ * // { name: "my-package", version: "1.0.0" }
+ *
+ * // Scoped packages work too:
+ * parsePackageRef("@scope/package@2.0.0")
+ * // { name: "@scope/package", version: "2.0.0" }
+ * ```
+ */
+export function parsePackageRef(ref) {
+    const atIdx = ref.lastIndexOf('@');
+    // Handle scoped packages like @scope/name - only split on @ after position 0
+    if (atIdx > 0) {
+        return {
+            name: ref.slice(0, atIdx),
+            version: ref.slice(atIdx + 1),
+        };
+    }
+    return { name: ref };
+}
+/**
+ * Convert URL path segments to a TreePath.
+ *
+ * Takes slash-separated, URL-encoded path segments and converts them to
+ * a TreePath of field variants.
+ *
+ * @param urlPath - URL path string (e.g., "inputs/sales/data" or "/inputs/sales/data")
+ * @returns TreePath of field segments
+ *
+ * @example
+ * ```ts
+ * urlPathToTreePath("inputs/sales/data")
+ * // [field("inputs"), field("sales"), field("data")]
+ *
+ * urlPathToTreePath("inputs/my%20field")
+ * // [field("inputs"), field("my field")]
+ *
+ * urlPathToTreePath("")
+ * // []
+ * ```
+ */
+export function urlPathToTreePath(urlPath) {
+    const segments = urlPath.split('/').filter(p => p);
+    return segments.map(segment => variant('field', decodeURIComponent(segment)));
+}
 //# sourceMappingURL=structure.js.map

package/dist/src/structure.js.map

@@ -1 +1 @@
-{"version":3,"file":"structure.js","sourceRoot":"","sources":["../../src/structure.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"structure.js","sourceRoot":"","sources":["../../src/structure.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAe,eAAe,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAEjJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,WAAW,CAAC;IAC7D,iEAAiE;IACjE,KAAK,EAAE,YAAY;IACnB,8DAA8D;IAC9D,MAAM,EAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;CACnC,CAAC,CAAC,CAAC;AAKJ,gCAAgC;AAChC,4CAA4C;AAC5C,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAC;AAM/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;IACzC,kCAAkC;IAClC,KAAK,EAAE,UAAU;IACjB,wDAAwD;IACxD,8CAA8C;IAC9C,2DAA2D;CAC5D,CAAC,CAAC;AAKH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC,eAAe,CAAC,CAAC;AAKvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAAC,IAAc;IACzC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE;QACxB,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;YAC7B,OAAO,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,gDAAgD,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAClF,CAAC;IACH,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAYD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,SAAoB;IAC7D,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;IAEnD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,gBAAgB,GAAG,SAAS,CAAC;IACjC,IAAI,GAAG,GAAG,CAAC,CAAC;IAEZ,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;YACzB,GAAG,EAAE,CAAC;YAEN,oEAAoE;YACpE,IAAI,SAAiB,CAAC;YAEtB,uCAAuC;YACvC,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;gBACjD,GAAG,EAAE,CAAC;gBACN,SAAS,GAAG,EAAE,CAAC;gBACf,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;oBACpD,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,IAAI,GAAG,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;wBACtD,kBAAkB;wBAClB,GAAG,EAAE,CAAC;wBACN,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;oBAC5B,CAAC;yBAAM,CAAC;wBACN,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;oBAC5B,CAAC;oBACD,GAAG,EAAE,CAAC;gBACR,CAAC;gBACD,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,GAAG,EAAE,CAAC;oBACjD,GAAG,EAAE,CAAC,CAAC,2BAA2B;gBACpC,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,4CAA4C;gBAC5C,SAAS,GAAG,EAAE,CAAC;gBACf,OAAO,GAAG,GAAG,OAAO,CAAC,MAAM,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAE,CAAC,EAAE,CAAC;oBAClE,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;oBAC1B,GAAG,EAAE,CAAC;gBACR,CAAC;YACH,CAAC;YAED,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CAAC,wDAAwD,GAAG,EAAE,CAAC,CAAC;YACjF,CAAC;YAED,6BAA6B;YAC7B,IAAI,gBAAgB,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACtC,MAAM,IAAI,KAAK,CAAC,8CAA8C,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC3F,CAAC;YAED,6EAA6E;YAC7E,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC;YACtC,MAAM,cAAc,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC7C,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;gBACjC,MAAM,SAAS,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC7E,MAAM,IAAI,KAAK,CAAC,qBAAqB,SAAS,mBAAmB,YAAY,CAAC,QAAQ,CAAC,iBAAiB,SAAS,EAAE,CAAC,CAAC;YACvH,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC;YAC3C,gBAAgB,GAAG,cAAc,CAAC;QACpC,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,+CAA+C,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3F,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,QAAQ,CAAC,SAAoB,EAAE,GAAG,MAAgB;IAChE,OAAO,SAAS,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;AAC3E,CAAC;AAYD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAE7C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC1C,CAAC;IAED,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;IACxB,MAAM,IAAI,GAAa,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IAEzE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,QAAgB;IACzC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,WAAW,GAAG,KAAK,CAAC;IAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;QAEzB,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC;YACjB,WAAW,GAAG,CAAC,WAAW,CAAC;QAC7B,CAAC;aAAM,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YACxC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACvB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACvB,OAAO,GAAG,EAAE,CAAC;YACf,CAAC;QACH,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,IAAI,CAAC;QAClB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IAED,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,6EAA6E;IAC7E,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,OAAO;YACL,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;YACzB,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;SAC9B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACnD,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/e3-types",
-  "version": "0.0.1-beta.0",
+  "version": "0.0.2-beta.1",
   "description": "Shared type definitions for e3 (East Execution Engine)",
   "type": "module",
   "main": "dist/src/index.js",
@@ -18,8 +18,13 @@
   ],
   "author": "Elara AI",
   "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elaraai/e3",
+    "directory": "packages/e3-types"
+  },
   "dependencies": {
-    "@elaraai/east": "0.0.1-beta.11"
+    "@elaraai/east": "^0.0.1-beta.14"
   },
   "devDependencies": {
     "@typescript-eslint/eslint-plugin": "^8.47.0",

package/src/index.ts

@@ -46,9 +46,14 @@ export {
   TreePathType,
   type TreePath,
   type ParsePathResult,
+  type ParseDatasetPathResult,
+  type ParsePackageRefResult,
   treePath,
   pathToString,
   parsePath,
+  parseDatasetPath,
+  parsePackageRef,
+  urlPathToTreePath,
   // Backwards compatibility
   DatasetSchemaType,
   type DatasetSchema,

package/src/structure.ts

@@ -268,3 +268,152 @@ export function parsePath(pathStr: string, structure: Structure): ParsePathResul
 export function treePath(structure: Structure, ...fields: string[]): ParsePathResult {
   return parsePath('.' + fields.map(printIdentifier).join('.'), structure);
 }
+
+/**
+ * Result of parsing a dataset path specification.
+ */
+export interface ParseDatasetPathResult {
+  /** Workspace name */
+  ws: string;
+  /** Path within the workspace */
+  path: TreePath;
+}
+
+/**
+ * Parse workspace.path.to.dataset syntax into workspace name and TreePath.
+ *
+ * This is a lenient parser that does not validate against a structure.
+ * Use this for parsing user input where the structure is not yet known.
+ *
+ * @param pathSpec - Path specification in dot notation (e.g., "production.inputs.sales")
+ * @returns Workspace name and path segments
+ *
+ * @throws {Error} If path is empty or has unclosed backticks
+ *
+ * @example
+ * ```ts
+ * parseDatasetPath("production")
+ * // { ws: "production", path: [] }
+ *
+ * parseDatasetPath("production.inputs.sales")
+ * // { ws: "production", path: [field("inputs"), field("sales")] }
+ *
+ * // For field names with special characters, use backticks:
+ * parseDatasetPath("production.`my field`")
+ * // { ws: "production", path: [field("my field")] }
+ * ```
+ */
+export function parseDatasetPath(pathSpec: string): ParseDatasetPathResult {
+  const segments = parsePathSegments(pathSpec);
+
+  if (segments.length === 0) {
+    throw new Error('Path cannot be empty');
+  }
+
+  const ws = segments[0]!;
+  const path: TreePath = segments.slice(1).map((s) => variant('field', s));
+
+  return { ws, path };
+}
+
+/**
+ * Parse dot-separated path into segments, handling backtick-quoted identifiers.
+ * @internal
+ */
+function parsePathSegments(pathSpec: string): string[] {
+  const segments: string[] = [];
+  let current = '';
+  let inBackticks = false;
+
+  for (let i = 0; i < pathSpec.length; i++) {
+    const char = pathSpec[i];
+
+    if (char === '`') {
+      inBackticks = !inBackticks;
+    } else if (char === '.' && !inBackticks) {
+      if (current.length > 0) {
+        segments.push(current);
+        current = '';
+      }
+    } else {
+      current += char;
+    }
+  }
+
+  if (current.length > 0) {
+    segments.push(current);
+  }
+
+  if (inBackticks) {
+    throw new Error('Unclosed backtick in path');
+  }
+
+  return segments;
+}
+
+/**
+ * Result of parsing a package reference.
+ */
+export interface ParsePackageRefResult {
+  /** Package name */
+  name: string;
+  /** Version string, or undefined if not specified */
+  version?: string;
+}
+
+/**
+ * Parse a package reference like "name" or "name@version".
+ *
+ * @param ref - Package reference string
+ * @returns Package name and optional version
+ *
+ * @example
+ * ```ts
+ * parsePackageRef("my-package")
+ * // { name: "my-package", version: undefined }
+ *
+ * parsePackageRef("my-package@1.0.0")
+ * // { name: "my-package", version: "1.0.0" }
+ *
+ * // Scoped packages work too:
+ * parsePackageRef("@scope/package@2.0.0")
+ * // { name: "@scope/package", version: "2.0.0" }
+ * ```
+ */
+export function parsePackageRef(ref: string): ParsePackageRefResult {
+  const atIdx = ref.lastIndexOf('@');
+  // Handle scoped packages like @scope/name - only split on @ after position 0
+  if (atIdx > 0) {
+    return {
+      name: ref.slice(0, atIdx),
+      version: ref.slice(atIdx + 1),
+    };
+  }
+  return { name: ref };
+}
+
+/**
+ * Convert URL path segments to a TreePath.
+ *
+ * Takes slash-separated, URL-encoded path segments and converts them to
+ * a TreePath of field variants.
+ *
+ * @param urlPath - URL path string (e.g., "inputs/sales/data" or "/inputs/sales/data")
+ * @returns TreePath of field segments
+ *
+ * @example
+ * ```ts
+ * urlPathToTreePath("inputs/sales/data")
+ * // [field("inputs"), field("sales"), field("data")]
+ *
+ * urlPathToTreePath("inputs/my%20field")
+ * // [field("inputs"), field("my field")]
+ *
+ * urlPathToTreePath("")
+ * // []
+ * ```
+ */
+export function urlPathToTreePath(urlPath: string): TreePath {
+  const segments = urlPath.split('/').filter(p => p);
+  return segments.map(segment => variant('field', decodeURIComponent(segment)));
+}