@elaraai/e3-types 0.0.1-alpha.2

package/dist/src/package.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Package object types for e3.
+ *
+ * A package bundles everything needed to run computations:
+ * tasks and data structure with initial values.
+ *
+ * Terminology:
+ * - **Package**: A deployable bundle of tasks and data structure
+ * - **Structure**: The shape of the data tree
+ * - **Task**: A computation with input/output paths (stored separately)
+ */
+import { StructType, StringType, DictType, ValueTypeOf } from '@elaraai/east';
+/**
+ * Data configuration in a package.
+ *
+ * Defines the structure (which paths are datasets vs trees)
+ * and initial values (root tree hash).
+ *
+ * @remarks
+ * - `structure`: Defines which paths are datasets vs trees (recursive)
+ * - `value`: Hash of the root tree object in the object store
+ *
+ * @example
+ * ```ts
+ * const data: PackageData = {
+ *   structure: variant('struct', new Map([
+ *     ['inputs', variant('struct', new Map([
+ *       ['sales', variant('value', variant('Array', variant('Integer', null)))],
+ *     ]))],
+ *     ['tasks', variant('struct', new Map([
+ *       ['process', variant('struct', new Map([
+ *         ['function_ir', variant('value', ...)],
+ *         ['output', variant('value', variant('Integer', null))],
+ *       ]))],
+ *     ]))],
+ *   ])),
+ *   value: 'abc123...',  // Hash of initial tree
+ * };
+ * ```
+ */
+export declare const PackageDataType: StructType<{
+    /** Structure defining tree shape (what's a group vs dataset) */
+    structure: import("@elaraai/east").RecursiveType<import("@elaraai/east").VariantType<{
+        value: import("@elaraai/east").RecursiveType<import("@elaraai/east").VariantType<{
+            Never: import("@elaraai/east").NullType;
+            Null: import("@elaraai/east").NullType;
+            Boolean: import("@elaraai/east").NullType;
+            Integer: import("@elaraai/east").NullType;
+            Float: import("@elaraai/east").NullType;
+            String: import("@elaraai/east").NullType;
+            DateTime: import("@elaraai/east").NullType;
+            Blob: import("@elaraai/east").NullType;
+            Ref: import("@elaraai/east").RecursiveTypeMarker;
+            Array: import("@elaraai/east").RecursiveTypeMarker;
+            Set: import("@elaraai/east").RecursiveTypeMarker;
+            Dict: StructType<{
+                key: import("@elaraai/east").RecursiveTypeMarker;
+                value: import("@elaraai/east").RecursiveTypeMarker;
+            }>;
+            Struct: import("@elaraai/east").ArrayType<StructType<{
+                name: StringType;
+                type: import("@elaraai/east").RecursiveTypeMarker;
+            }>>;
+            Variant: import("@elaraai/east").ArrayType<StructType<{
+                name: StringType;
+                type: import("@elaraai/east").RecursiveTypeMarker;
+            }>>;
+            Recursive: import("@elaraai/east").IntegerType;
+            Function: StructType<{
+                inputs: import("@elaraai/east").ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                output: import("@elaraai/east").RecursiveTypeMarker;
+            }>;
+            AsyncFunction: StructType<{
+                inputs: import("@elaraai/east").ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                output: import("@elaraai/east").RecursiveTypeMarker;
+            }>;
+        }>>;
+        struct: DictType<StringType, import("@elaraai/east").RecursiveTypeMarker>;
+    }>>;
+    /** Hash of the root tree object containing initial/default values */
+    value: StringType;
+}>;
+export type PackageDataType = typeof PackageDataType;
+export type PackageData = ValueTypeOf<typeof PackageDataType>;
+/** @deprecated Use PackageDataType instead */
+export declare const PackageDatasetsType: StructType<{
+    /** Structure defining tree shape (what's a group vs dataset) */
+    structure: import("@elaraai/east").RecursiveType<import("@elaraai/east").VariantType<{
+        value: import("@elaraai/east").RecursiveType<import("@elaraai/east").VariantType<{
+            Never: import("@elaraai/east").NullType;
+            Null: import("@elaraai/east").NullType;
+            Boolean: import("@elaraai/east").NullType;
+            Integer: import("@elaraai/east").NullType;
+            Float: import("@elaraai/east").NullType;
+            String: import("@elaraai/east").NullType;
+            DateTime: import("@elaraai/east").NullType;
+            Blob: import("@elaraai/east").NullType;
+            Ref: import("@elaraai/east").RecursiveTypeMarker;
+            Array: import("@elaraai/east").RecursiveTypeMarker;
+            Set: import("@elaraai/east").RecursiveTypeMarker;
+            Dict: StructType<{
+                key: import("@elaraai/east").RecursiveTypeMarker;
+                value: import("@elaraai/east").RecursiveTypeMarker;
+            }>;
+            Struct: import("@elaraai/east").ArrayType<StructType<{
+                name: StringType;
+                type: import("@elaraai/east").RecursiveTypeMarker;
+            }>>;
+            Variant: import("@elaraai/east").ArrayType<StructType<{
+                name: StringType;
+                type: import("@elaraai/east").RecursiveTypeMarker;
+            }>>;
+            Recursive: import("@elaraai/east").IntegerType;
+            Function: StructType<{
+                inputs: import("@elaraai/east").ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                output: import("@elaraai/east").RecursiveTypeMarker;
+            }>;
+            AsyncFunction: StructType<{
+                inputs: import("@elaraai/east").ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                output: import("@elaraai/east").RecursiveTypeMarker;
+            }>;
+        }>>;
+        struct: DictType<StringType, import("@elaraai/east").RecursiveTypeMarker>;
+    }>>;
+    /** Hash of the root tree object containing initial/default values */
+    value: StringType;
+}>;
+/** @deprecated Use PackageData instead */
+export type PackageDatasetsType = PackageDataType;
+/** @deprecated Use PackageData instead */
+export type PackageDatasets = PackageData;
+/**
+ * Package object stored in the object store.
+ *
+ * Packages are the unit of distribution and deployment in e3.
+ * They are immutable and content-addressed by their hash.
+ *
+ * @remarks
+ * - `tasks`: Maps task names to task object hashes. Each task object
+ *   contains runner, input paths, and output path.
+ * - `data`: The structure and initial values for the data tree.
+ *
+ * Package identity (name/version) is determined by the path in the
+ * bundle's `packages/<name>/<version>` directory structure.
+ *
+ * @example
+ * ```ts
+ * const pkg: PackageObject = {
+ *   tasks: new Map([['process', 'abc123...']]),  // hash of TaskObject
+ *   data: {
+ *     structure: variant('struct', new Map([...])),
+ *     value: 'def456...',  // hash of root tree
+ *   },
+ * };
+ * ```
+ */
+export declare const PackageObjectType: StructType<{
+    /** Tasks defined in this package: name -> task object hash */
+    tasks: DictType<StringType, StringType>;
+    /** Data structure and initial values */
+    data: StructType<{
+        /** Structure defining tree shape (what's a group vs dataset) */
+        structure: import("@elaraai/east").RecursiveType<import("@elaraai/east").VariantType<{
+            value: import("@elaraai/east").RecursiveType<import("@elaraai/east").VariantType<{
+                Never: import("@elaraai/east").NullType;
+                Null: import("@elaraai/east").NullType;
+                Boolean: import("@elaraai/east").NullType;
+                Integer: import("@elaraai/east").NullType;
+                Float: import("@elaraai/east").NullType;
+                String: import("@elaraai/east").NullType;
+                DateTime: import("@elaraai/east").NullType;
+                Blob: import("@elaraai/east").NullType;
+                Ref: import("@elaraai/east").RecursiveTypeMarker;
+                Array: import("@elaraai/east").RecursiveTypeMarker;
+                Set: import("@elaraai/east").RecursiveTypeMarker;
+                Dict: StructType<{
+                    key: import("@elaraai/east").RecursiveTypeMarker;
+                    value: import("@elaraai/east").RecursiveTypeMarker;
+                }>;
+                Struct: import("@elaraai/east").ArrayType<StructType<{
+                    name: StringType;
+                    type: import("@elaraai/east").RecursiveTypeMarker;
+                }>>;
+                Variant: import("@elaraai/east").ArrayType<StructType<{
+                    name: StringType;
+                    type: import("@elaraai/east").RecursiveTypeMarker;
+                }>>;
+                Recursive: import("@elaraai/east").IntegerType;
+                Function: StructType<{
+                    inputs: import("@elaraai/east").ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                    output: import("@elaraai/east").RecursiveTypeMarker;
+                }>;
+                AsyncFunction: StructType<{
+                    inputs: import("@elaraai/east").ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                    output: import("@elaraai/east").RecursiveTypeMarker;
+                }>;
+            }>>;
+            struct: DictType<StringType, import("@elaraai/east").RecursiveTypeMarker>;
+        }>>;
+        /** Hash of the root tree object containing initial/default values */
+        value: StringType;
+    }>;
+}>;
+export type PackageObjectType = typeof PackageObjectType;
+export type PackageObject = ValueTypeOf<typeof PackageObjectType>;
+//# sourceMappingURL=package.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"package.d.ts","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG9E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,eAAe;IAC1B,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEhE,qEAAqE;;EAErE,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC;AAErD,MAAM,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,eAAe,CAAC,CAAC;AAG9D,8CAA8C;AAC9C,eAAO,MAAM,mBAAmB;IAX9B,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAEhE,qEAAqE;;EASrB,CAAC;AACnD,0CAA0C;AAC1C,MAAM,MAAM,mBAAmB,GAAG,eAAe,CAAC;AAClD,0CAA0C;AAC1C,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,iBAAiB;IAC5B,8DAA8D;;IAE9D,wCAAwC;;QA7CxC,gEAAgE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAEhE,qEAAqE;;;EA6CrE,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/src/package.js

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Package object types for e3.
+ *
+ * A package bundles everything needed to run computations:
+ * tasks and data structure with initial values.
+ *
+ * Terminology:
+ * - **Package**: A deployable bundle of tasks and data structure
+ * - **Structure**: The shape of the data tree
+ * - **Task**: A computation with input/output paths (stored separately)
+ */
+import { StructType, StringType, DictType } from '@elaraai/east';
+import { StructureType } from './structure.js';
+/**
+ * Data configuration in a package.
+ *
+ * Defines the structure (which paths are datasets vs trees)
+ * and initial values (root tree hash).
+ *
+ * @remarks
+ * - `structure`: Defines which paths are datasets vs trees (recursive)
+ * - `value`: Hash of the root tree object in the object store
+ *
+ * @example
+ * ```ts
+ * const data: PackageData = {
+ *   structure: variant('struct', new Map([
+ *     ['inputs', variant('struct', new Map([
+ *       ['sales', variant('value', variant('Array', variant('Integer', null)))],
+ *     ]))],
+ *     ['tasks', variant('struct', new Map([
+ *       ['process', variant('struct', new Map([
+ *         ['function_ir', variant('value', ...)],
+ *         ['output', variant('value', variant('Integer', null))],
+ *       ]))],
+ *     ]))],
+ *   ])),
+ *   value: 'abc123...',  // Hash of initial tree
+ * };
+ * ```
+ */
+export const PackageDataType = StructType({
+    /** Structure defining tree shape (what's a group vs dataset) */
+    structure: StructureType,
+    /** Hash of the root tree object containing initial/default values */
+    value: StringType,
+});
+// Backwards compatibility alias
+/** @deprecated Use PackageDataType instead */
+export const PackageDatasetsType = PackageDataType;
+/**
+ * Package object stored in the object store.
+ *
+ * Packages are the unit of distribution and deployment in e3.
+ * They are immutable and content-addressed by their hash.
+ *
+ * @remarks
+ * - `tasks`: Maps task names to task object hashes. Each task object
+ *   contains runner, input paths, and output path.
+ * - `data`: The structure and initial values for the data tree.
+ *
+ * Package identity (name/version) is determined by the path in the
+ * bundle's `packages/<name>/<version>` directory structure.
+ *
+ * @example
+ * ```ts
+ * const pkg: PackageObject = {
+ *   tasks: new Map([['process', 'abc123...']]),  // hash of TaskObject
+ *   data: {
+ *     structure: variant('struct', new Map([...])),
+ *     value: 'def456...',  // hash of root tree
+ *   },
+ * };
+ * ```
+ */
+export const PackageObjectType = StructType({
+    /** Tasks defined in this package: name -> task object hash */
+    tasks: DictType(StringType, StringType),
+    /** Data structure and initial values */
+    data: PackageDataType,
+});
+//# sourceMappingURL=package.js.map

package/dist/src/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAe,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;IACxC,gEAAgE;IAChE,SAAS,EAAE,aAAa;IACxB,qEAAqE;IACrE,KAAK,EAAE,UAAU;CAClB,CAAC,CAAC;AAKH,gCAAgC;AAChC,8CAA8C;AAC9C,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC;AAMnD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC;IAC1C,8DAA8D;IAC9D,KAAK,EAAE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IACvC,wCAAwC;IACxC,IAAI,EAAE,eAAe;CACtB,CAAC,CAAC"}

package/dist/src/structure.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Data structure and path types for e3.
+ *
+ * Terminology:
+ * - **Dataset**: A location holding a value (leaf node in the data tree)
+ * - **Tree**: A location containing datasets or nested trees (branch node)
+ * - **Structure**: The shape of the data tree (what trees/datasets exist and their types)
+ * - **Path**: An address pointing to a dataset or tree
+ *
+ * Paths use East's keypath syntax:
+ * - `.field` for struct field access (backtick-quoted for special chars)
+ * - `[N]` for array index access (future)
+ * - `[key]` for dict key lookup (future)
+ *
+ * @see East serialization docs for keypath syntax details
+ */
+import { VariantType, StringType, ArrayType, DictType, RecursiveType, ValueTypeOf } from '@elaraai/east';
+/**
+ * Structure definition for a data tree node.
+ *
+ * Defines the shape of the data tree - which paths are datasets (hold values)
+ * and which are trees (hold other nodes).
+ *
+ * @remarks
+ * - `value`: A dataset - holds a typed value. The type is an `EastTypeValue`.
+ * - `struct`: A tree - has named children, each with its own structure.
+ *
+ * MVP only supports struct trees. Future: array, dict, variant trees.
+ *
+ * @example
+ * ```ts
+ * // A dataset holding an Integer value
+ * const dataset: Structure = variant('value', variant('Integer', null));
+ *
+ * // A tree with named children
+ * const tree: Structure = variant('struct', new Map([
+ *   ['count', variant('value', variant('Integer', null))],
+ *   ['items', variant('value', variant('Array', variant('String', null)))],
+ * ]));
+ * ```
+ */
+export declare const StructureType: RecursiveType<VariantType<{
+    /** Dataset: East type of the value (homoiconic EastTypeValue) */
+    value: RecursiveType<VariantType<{
+        Never: import("@elaraai/east").NullType;
+        Null: import("@elaraai/east").NullType;
+        Boolean: import("@elaraai/east").NullType;
+        Integer: import("@elaraai/east").NullType;
+        Float: import("@elaraai/east").NullType;
+        String: import("@elaraai/east").NullType;
+        DateTime: import("@elaraai/east").NullType;
+        Blob: import("@elaraai/east").NullType;
+        Ref: import("@elaraai/east").RecursiveTypeMarker;
+        Array: import("@elaraai/east").RecursiveTypeMarker;
+        Set: import("@elaraai/east").RecursiveTypeMarker;
+        Dict: import("@elaraai/east").StructType<{
+            key: import("@elaraai/east").RecursiveTypeMarker;
+            value: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        Struct: ArrayType<import("@elaraai/east").StructType<{
+            name: StringType;
+            type: import("@elaraai/east").RecursiveTypeMarker;
+        }>>;
+        Variant: ArrayType<import("@elaraai/east").StructType<{
+            name: StringType;
+            type: import("@elaraai/east").RecursiveTypeMarker;
+        }>>;
+        Recursive: import("@elaraai/east").IntegerType;
+        Function: import("@elaraai/east").StructType<{
+            inputs: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+            output: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        AsyncFunction: import("@elaraai/east").StructType<{
+            inputs: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+            output: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+    }>>;
+    /** Struct tree: named children mapping to child structures */
+    struct: DictType<StringType, import("@elaraai/east").RecursiveTypeMarker>;
+}>>;
+export type StructureType = typeof StructureType;
+export type Structure = ValueTypeOf<typeof StructureType>;
+/** @deprecated Use StructureType instead */
+export declare const DatasetSchemaType: RecursiveType<VariantType<{
+    /** Dataset: East type of the value (homoiconic EastTypeValue) */
+    value: RecursiveType<VariantType<{
+        Never: import("@elaraai/east").NullType;
+        Null: import("@elaraai/east").NullType;
+        Boolean: import("@elaraai/east").NullType;
+        Integer: import("@elaraai/east").NullType;
+        Float: import("@elaraai/east").NullType;
+        String: import("@elaraai/east").NullType;
+        DateTime: import("@elaraai/east").NullType;
+        Blob: import("@elaraai/east").NullType;
+        Ref: import("@elaraai/east").RecursiveTypeMarker;
+        Array: import("@elaraai/east").RecursiveTypeMarker;
+        Set: import("@elaraai/east").RecursiveTypeMarker;
+        Dict: import("@elaraai/east").StructType<{
+            key: import("@elaraai/east").RecursiveTypeMarker;
+            value: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        Struct: ArrayType<import("@elaraai/east").StructType<{
+            name: StringType;
+            type: import("@elaraai/east").RecursiveTypeMarker;
+        }>>;
+        Variant: ArrayType<import("@elaraai/east").StructType<{
+            name: StringType;
+            type: import("@elaraai/east").RecursiveTypeMarker;
+        }>>;
+        Recursive: import("@elaraai/east").IntegerType;
+        Function: import("@elaraai/east").StructType<{
+            inputs: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+            output: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        AsyncFunction: import("@elaraai/east").StructType<{
+            inputs: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+            output: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+    }>>;
+    /** Struct tree: named children mapping to child structures */
+    struct: DictType<StringType, import("@elaraai/east").RecursiveTypeMarker>;
+}>>;
+/** @deprecated Use Structure instead */
+export type DatasetSchemaType = StructureType;
+/** @deprecated Use Structure instead */
+export type DatasetSchema = Structure;
+/**
+ * Path segment for navigating data trees.
+ *
+ * Uses East keypath syntax for consistency:
+ * - `field`: Struct field access (rendered as `.field` or `` .`field` `` if quoted)
+ * - `index`: Array element access (rendered as `[N]`) - future
+ * - `key`: Dict key lookup (rendered as `[key]`) - future
+ *
+ * @example
+ * ```ts
+ * // Struct field access
+ * const segment: PathSegment = variant('field', 'sales');
+ *
+ * // Array index (future)
+ * const segment: PathSegment = variant('index', 0n);
+ * ```
+ */
+export declare const PathSegmentType: VariantType<{
+    /** Struct field access by name */
+    field: StringType;
+}>;
+export type PathSegmentType = typeof PathSegmentType;
+export type PathSegment = ValueTypeOf<typeof PathSegmentType>;
+/**
+ * Path: sequence of segments identifying a location in a data tree.
+ *
+ * Paths point to either a dataset (leaf) or a tree (branch).
+ * Used by tasks to specify where inputs come from and where outputs go.
+ *
+ * @example
+ * ```ts
+ * // Path to .inputs.sales.data
+ * const path: TreePath = [
+ *   variant('field', 'inputs'),
+ *   variant('field', 'sales'),
+ *   variant('field', 'data'),
+ * ];
+ * ```
+ */
+export declare const TreePathType: ArrayType<VariantType<{
+    /** Struct field access by name */
+    field: StringType;
+}>>;
+export type TreePathType = typeof TreePathType;
+export type TreePath = ValueTypeOf<typeof TreePathType>;
+/**
+ * Converts a path to East keypath string representation.
+ *
+ * Uses East's keypath syntax: `.field` for simple identifiers,
+ * `` .`field` `` for identifiers needing quoting.
+ *
+ * @param path - The path to convert
+ * @returns A keypath string (e.g., ".inputs.sales" or ".inputs.`my/field`")
+ *
+ * @example
+ * ```ts
+ * const path = treePath('inputs', 'sales');
+ * pathToString(path); // ".inputs.sales"
+ *
+ * const path2 = treePath('inputs', 'my/field');
+ * pathToString(path2); // ".inputs.`my/field`"
+ * ```
+ */
+export declare function pathToString(path: TreePath): string;
+/**
+ * Result of parsing a path with structure validation.
+ */
+export interface ParsePathResult {
+    /** The parsed path segments */
+    path: TreePath;
+    /** The structure at the path location */
+    structure: Structure;
+}
+/**
+ * Parses an East keypath string into a path, validating against the structure.
+ *
+ * Supports `.field` syntax for struct field access.
+ * Backtick-quoted identifiers (`` .`field` ``) are supported for special chars.
+ *
+ * @param pathStr - A keypath string (e.g., ".inputs.sales")
+ * @param structure - The root structure to validate against
+ * @returns The parsed path and the structure at that location
+ *
+ * @throws {Error} If a field doesn't exist in the structure or path descends into a dataset
+ *
+ * @remarks
+ * - Empty string returns empty path (root) with the root structure
+ * - Path must start with `.` (no leading slash)
+ * - Backtick escaping: `` \` `` for literal backtick, `\\` for backslash
+ * - Future: will disambiguate variant cases from struct fields using structure
+ * - Future: will use structure to parse dict keys with correct type
+ *
+ * @example
+ * ```ts
+ * const structure = variant('struct', new Map([
+ *   ['inputs', variant('struct', new Map([
+ *     ['sales', variant('value', variant('Integer', null))],
+ *   ]))],
+ * ]));
+ *
+ * const { path, structure: leafStructure } = parsePath('.inputs.sales', structure);
+ * // path = [field('inputs'), field('sales')]
+ * // leafStructure = variant('value', variant('Integer', null))
+ * ```
+ */
+export declare function parsePath(pathStr: string, structure: Structure): ParsePathResult;
+/**
+ * Creates a path from field names, validating against the structure.
+ *
+ * Convenience function for the common case of navigating through struct fields.
+ *
+ * @param structure - The root structure to validate against
+ * @param fields - Field names to include in the path
+ * @returns The parsed path and the structure at that location
+ *
+ * @throws {Error} If a field doesn't exist in the structure
+ *
+ * @example
+ * ```ts
+ * const { path, structure: leafStructure } = treePath(rootStructure, 'inputs', 'sales');
+ * ```
+ */
+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

@@ -0,0 +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;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"}