@elaraai/east-ui 0.0.1-beta.6 → 0.0.1-beta.7

package/dist/src/platform/state.d.ts

@@ -2,101 +2,202 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-import { StringType, BlobType, NullType } from "@elaraai/east";
-import type { PlatformFunctionDef } from "@elaraai/east/internal";
+/**
+ * State management platform functions for East UI.
+ *
+ * Provides reactive state operations for East UI programs.
+ * State is stored as Beast2-encoded blobs, allowing any East type to be stored.
+ *
+ * @packageDocumentation
+ */
+import { StringType, BlobType, NullType, type SubtypeExprOrValue, type EastType, type CallableFunctionExpr, BooleanType } from "@elaraai/east";
+import { type PlatformFunction, OptionType } from "@elaraai/east/internal";
+import { UIStore } from "./store.js";
+/**
+ * Enable dependency tracking for reactive components.
+ *
+ * @remarks
+ * Call this before executing a reactive component's render function.
+ * All subsequent `state_read` calls will record their keys to the tracking set.
+ * Call {@link disableTracking} when done to get the collected keys.
+ *
+ * @returns The Set that will collect accessed keys
+ *
+ * @example
+ * ```ts
+ * enableTracking();
+ * try {
+ *     const result = renderFn();
+ *     const deps = disableTracking();
+ *     // deps contains all state keys read during renderFn()
+ * } catch (e) {
+ *     disableTracking();
+ *     throw e;
+ * }
+ * ```
+ */
+export declare function enableTracking(): Set<string>;
+/**
+ * Disable dependency tracking and return collected keys.
+ *
+ * @remarks
+ * Call this after executing a reactive component's render function.
+ * Returns all keys that were accessed via `state_read` since {@link enableTracking} was called.
+ *
+ * @returns Array of state keys that were read during tracking
+ */
+export declare function disableTracking(): string[];
+/**
+ * Check if dependency tracking is currently enabled.
+ *
+ * @returns True if tracking is active
+ */
+export declare function isTracking(): boolean;
+/**
+ * Record a key access during dependency tracking.
+ *
+ * @remarks
+ * Called internally by the `state_read` implementation.
+ * Only records if tracking is enabled via {@link enableTracking}.
+ *
+ * @param key - The state key being accessed
+ */
+export declare function trackKey(key: string): void;
 /**
  * Platform function to write a Beast2-encoded value to the state store.
  *
- * This is a platform function for the East language, enabling state management
- * in East UI applications. The implementation is provided by the React store
- * in `@elaraai/east-ui-components`.
+ * @remarks
+ * Writes a blob to state, or deletes the key if `none` is passed.
+ * Triggers re-render in reactive contexts.
  *
  * @param key - The string key to write to
- * @param value - The Beast2-encoded blob value
+ * @param value - The Beast2-encoded blob value (some to write, none to delete)
  * @returns Null
+ */
+export declare const state_write: import("@elaraai/east").PlatformDefinition<[StringType, OptionType<BlobType>], NullType>;
+/**
+ * Platform function to read a Beast2-encoded value from the state store.
+ *
+ * @remarks
+ * Returns `some(blob)` if the key exists, `none` if not.
+ * Use `.match()` to handle both cases.
+ *
+ * @param key - The string key to read from
+ * @returns Option of Beast2-encoded blob (some if exists, none if not)
+ */
+export declare const state_read: import("@elaraai/east").PlatformDefinition<[StringType], OptionType<BlobType>>;
+/**
+ * Platform function to check if a key exists in the state store.
+ *
+ * @remarks
+ * Returns true if the key exists, false otherwise.
+ *
+ * @param key - The string key to check
+ * @returns Boolean indicating existence of the key
+ */
+export declare const state_has: import("@elaraai/east").PlatformDefinition<[StringType], BooleanType>;
+/**
+ * Singleton UI store instance for state management.
+ *
+ * @remarks
+ * This is the global store used by {@link StateImpl}. Access directly
+ * for React integration, subscriptions, or debugging.
+ */
+export declare const store: UIStore;
+/**
+ * Platform implementation for state management operations.
+ *
+ * @remarks
+ * Provides the runtime implementations for state read/write operations
+ * bound to the singleton {@link store}. Pass this to `ir.compile()` to enable
+ * state functionality.
+ */
+export declare const StateImpl: PlatformFunction[];
+/**
+ * Creates a typed state write function for a given key and type.
+ *
+ * @remarks
+ * Returns an East function that writes a typed value to state. The value is
+ * automatically Beast2-encoded before storage. Pass `some(value)` to write
+ * or `none` to delete the key.
+ *
+ * @typeParam T - The East type of the value to write
+ * @param key - The string key to write to
+ * @param value - The value wrapped in an option (some to write, none to delete)
+ * @param type - The East type descriptor for the value
+ * @returns A callable East function that performs the write
  *
  * @example
  * ```ts
- * const updateCount = East.function(
- *     [['state', DictType(StringType, BlobType)]],
- *     NullType,
- *     ($, state) => {
- *         const countBlob = state.get("count");
- *         const count = countBlob.decodeBeast(IntegerType);
- *         $(State.write("count", East.Blob.encodeBeast(count.add(1n))));
- *     }
- * );
+ * import { East, IntegerType, NullType, some } from "@elaraai/east";
+ * import { State, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const counter = East.function([], UIComponentType, $ => {
+ *     // Write 42 to "counter" key
+ *     $(State.writeTyped("counter", some(42n), IntegerType)());
+ *
+ *     // Delete the key
+ *     $(State.writeTyped("counter", none, IntegerType)());
+ * });
  * ```
  */
-export declare const state_write: PlatformFunctionDef<[typeof StringType, typeof BlobType], typeof NullType>;
+export declare const state_write_typed: <T extends EastType>(key: SubtypeExprOrValue<StringType>, value: SubtypeExprOrValue<OptionType<T>>, type: T) => CallableFunctionExpr<[], NullType>;
 /**
- * Platform function to read a Beast2-encoded value from the state store.
- * Returns an empty blob if the key doesn't exist.
+ * Creates a typed state read function for a given key and type.
  *
- * This is a platform function for the East language, enabling state management
- * in East UI applications. The implementation is provided by the React store
- * in `@elaraai/east-ui-components`.
+ * @remarks
+ * Returns an East function that reads a typed value from state. The value is
+ * automatically Beast2-decoded after retrieval. Returns `some(value)` if the
+ * key exists, `none` if not.
  *
+ * @typeParam T - The East type of the value to read
  * @param key - The string key to read from
- * @returns The Beast2-encoded blob value
+ * @param type - The East type descriptor for the value
+ * @returns A callable East function that returns an option of the typed value
  *
  * @example
  * ```ts
- * const readCount = East.function([], IntegerType, ($) => {
- *     const blob = State.read("count");
- *     return blob.decodeBeast(IntegerType);
+ * import { East, IntegerType, NullType } from "@elaraai/east";
+ * import { State, UIComponentType, Text } from "@elaraai/east-ui";
+ *
+ * const display = East.function([], UIComponentType, $ => {
+ *     // Read typed value from state
+ *     const count = $.let(State.readTyped("counter", IntegerType)());
+ *
+ *     // Use the value (unwrap if you know it exists)
+ *     return Text.Root(East.str`Count: ${count.unwrap("some")}`);
  * });
  * ```
  */
-export declare const state_read: PlatformFunctionDef<[typeof StringType], typeof BlobType>;
+export declare const state_read_typed: <T extends EastType>(key: SubtypeExprOrValue<StringType>, type: T) => CallableFunctionExpr<[], OptionType<T>>;
 /**
- * Grouped state management platform functions.
+ * Creates a typed state initialization function that only writes if the key doesn't exist.
  *
- * Provides reactive state operations for East UI programs.
- * The implementation is created by the EastStore in `@elaraai/east-ui-components`.
+ * @remarks
+ * Returns an East function that initializes a state key with a default value.
+ * The write only occurs if the key is not already set, preventing overwrites
+ * on re-renders. Use this for setting up initial state in components.
+ *
+ * @typeParam T - The East type of the value to initialize
+ * @param key - The string key to initialize
+ * @param value - The default value to write (not wrapped in option)
+ * @param type - The East type descriptor for the value
+ * @returns A callable East function that performs the conditional initialization
  *
  * @example
  * ```ts
- * import { East, DictType, StringType, BlobType, IntegerType } from "@elaraai/east";
- * import { State } from "@elaraai/east-ui";
- * import { createEastStore } from "@elaraai/east-ui-components";
- *
- * const counter = East.function(
- *     [['state', DictType(StringType, BlobType)]],
- *     UIComponentType,
- *     ($, state) => {
- *         // Read current count
- *         const countBlob = state.get("count");
- *         const count = countBlob.decodeBeast(IntegerType);
- *
- *         // Write incremented count
- *         $(State.write("count", East.Blob.encodeBeast(count.add(1n))));
- *
- *         return Text.Root(East.str`Count: ${count}`);
- *     }
- * );
- *
- * // Create store and register function
- * const store = createEastStore();
- * store.register("counter", counter.toIR());
+ * import { East, IntegerType } from "@elaraai/east";
+ * import { State, UIComponentType, Button } from "@elaraai/east-ui";
+ *
+ * const counter = East.function([], UIComponentType, $ => {
+ *     // Initialize to 0 only if not already set
+ *     $(State.initTyped("counter", 0n, IntegerType)());
+ *
+ *     // Read and display
+ *     const count = $.let(State.readTyped("counter", IntegerType)());
+ *     // ...
+ * });
  * ```
  */
-export declare const State: {
-    /**
-     * Writes a Beast2-encoded value to the state store.
-     *
-     * @param key - The string key to write to
-     * @param value - The Beast2-encoded blob value
-     * @returns Null
-     */
-    readonly write: PlatformFunctionDef<[StringType, BlobType], NullType>;
-    /**
-     * Reads a Beast2-encoded value from the state store.
-     * Returns an empty blob if the key doesn't exist.
-     *
-     * @param key - The string key to read from
-     * @returns The Beast2-encoded blob value
-     */
-    readonly read: PlatformFunctionDef<[StringType], BlobType>;
-};
+export declare const state_init_typed: <T extends EastType>(key: SubtypeExprOrValue<StringType>, value: SubtypeExprOrValue<T>, type: T) => CallableFunctionExpr<[], NullType>;
 //# sourceMappingURL=state.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/platform/state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,WAAW,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,EAAE,OAAO,QAAQ,CAAC,EAAE,OAAO,QAAQ,CACjC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,UAAU,EAAE,mBAAmB,CAAC,CAAC,OAAO,UAAU,CAAC,EAAE,OAAO,QAAQ,CAC1B,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,KAAK;IACd;;;;;;OAMG;;IAGH;;;;;;OAMG;;CAEG,CAAC"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../../src/platform/state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAEH,UAAU,EACV,QAAQ,EACR,QAAQ,EAGR,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,WAAW,EACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAYrC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,IAAI,GAAG,CAAC,MAAM,CAAC,CAG5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAI1C;AAED;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI1C;AAMD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,0FAA6E,CAAC;AAEtG;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,gFAAkE,CAAC;AAE1F;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,uEAAwD,CAAC;AAI/E;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,SAAgB,CAAC;AAEnC;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,gBAAgB,EAsBvC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,QAAQ,EAChD,KAAK,kBAAkB,CAAC,UAAU,CAAC,EACnC,OAAO,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EACxC,MAAM,CAAC,KACR,oBAAoB,CAAC,EAAE,EAAE,QAAQ,CAcnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,QAAQ,EAC/C,KAAK,kBAAkB,CAAC,UAAU,CAAC,EACnC,MAAM,CAAC,KACR,oBAAoB,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,CAiBxC,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,QAAQ,EAC/C,KAAK,kBAAkB,CAAC,UAAU,CAAC,EACnC,OAAO,kBAAkB,CAAC,CAAC,CAAC,EAC5B,MAAM,CAAC,KACR,oBAAoB,CAAC,EAAE,EAAE,QAAQ,CAWnC,CAAC"}

package/dist/src/platform/state.js

@@ -2,100 +2,285 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
  */
-import { East, StringType, BlobType, NullType } from "@elaraai/east";
+/**
+ * State management platform functions for East UI.
+ *
+ * Provides reactive state operations for East UI programs.
+ * State is stored as Beast2-encoded blobs, allowing any East type to be stored.
+ *
+ * @packageDocumentation
+ */
+import { East, StringType, BlobType, NullType, none, some, BooleanType, } from "@elaraai/east";
+import { OptionType } from "@elaraai/east/internal";
+import { UIStore } from "./store.js";
+// =============================================================================
+// Reactive Dependency Tracking
+// =============================================================================
+/**
+ * Tracking context for reactive dependency collection.
+ * When set, state_read calls will record their keys here.
+ */
+let trackingContext = null;
+/**
+ * Enable dependency tracking for reactive components.
+ *
+ * @remarks
+ * Call this before executing a reactive component's render function.
+ * All subsequent `state_read` calls will record their keys to the tracking set.
+ * Call {@link disableTracking} when done to get the collected keys.
+ *
+ * @returns The Set that will collect accessed keys
+ *
+ * @example
+ * ```ts
+ * enableTracking();
+ * try {
+ *     const result = renderFn();
+ *     const deps = disableTracking();
+ *     // deps contains all state keys read during renderFn()
+ * } catch (e) {
+ *     disableTracking();
+ *     throw e;
+ * }
+ * ```
+ */
+export function enableTracking() {
+    trackingContext = new Set();
+    return trackingContext;
+}
+/**
+ * Disable dependency tracking and return collected keys.
+ *
+ * @remarks
+ * Call this after executing a reactive component's render function.
+ * Returns all keys that were accessed via `state_read` since {@link enableTracking} was called.
+ *
+ * @returns Array of state keys that were read during tracking
+ */
+export function disableTracking() {
+    const keys = trackingContext ? [...trackingContext] : [];
+    trackingContext = null;
+    return keys;
+}
+/**
+ * Check if dependency tracking is currently enabled.
+ *
+ * @returns True if tracking is active
+ */
+export function isTracking() {
+    return trackingContext !== null;
+}
+/**
+ * Record a key access during dependency tracking.
+ *
+ * @remarks
+ * Called internally by the `state_read` implementation.
+ * Only records if tracking is enabled via {@link enableTracking}.
+ *
+ * @param key - The state key being accessed
+ */
+export function trackKey(key) {
+    if (trackingContext) {
+        trackingContext.add(key);
+    }
+}
+// =============================================================================
+// Platform Functions
+// =============================================================================
 /**
  * Platform function to write a Beast2-encoded value to the state store.
  *
- * This is a platform function for the East language, enabling state management
- * in East UI applications. The implementation is provided by the React store
- * in `@elaraai/east-ui-components`.
+ * @remarks
+ * Writes a blob to state, or deletes the key if `none` is passed.
+ * Triggers re-render in reactive contexts.
  *
  * @param key - The string key to write to
- * @param value - The Beast2-encoded blob value
+ * @param value - The Beast2-encoded blob value (some to write, none to delete)
  * @returns Null
+ */
+export const state_write = East.platform("state_write", [StringType, OptionType(BlobType)], NullType);
+/**
+ * Platform function to read a Beast2-encoded value from the state store.
+ *
+ * @remarks
+ * Returns `some(blob)` if the key exists, `none` if not.
+ * Use `.match()` to handle both cases.
+ *
+ * @param key - The string key to read from
+ * @returns Option of Beast2-encoded blob (some if exists, none if not)
+ */
+export const state_read = East.platform("state_read", [StringType], OptionType(BlobType));
+/**
+ * Platform function to check if a key exists in the state store.
+ *
+ * @remarks
+ * Returns true if the key exists, false otherwise.
+ *
+ * @param key - The string key to check
+ * @returns Boolean indicating existence of the key
+ */
+export const state_has = East.platform("state_has", [StringType], BooleanType);
+/**
+ * Singleton UI store instance for state management.
+ *
+ * @remarks
+ * This is the global store used by {@link StateImpl}. Access directly
+ * for React integration, subscriptions, or debugging.
+ */
+export const store = new UIStore();
+/**
+ * Platform implementation for state management operations.
+ *
+ * @remarks
+ * Provides the runtime implementations for state read/write operations
+ * bound to the singleton {@link store}. Pass this to `ir.compile()` to enable
+ * state functionality.
+ */
+export const StateImpl = [
+    state_write.implement((key, value) => {
+        if (value.type === 'none') {
+            store.write(key, undefined);
+        }
+        else {
+            store.write(key, value.value);
+        }
+    }),
+    state_read.implement((key) => {
+        // Track the key if in tracking mode (for reactive dependency collection)
+        trackKey(key);
+        const ret = store.read(key);
+        if (ret === undefined) {
+            return none;
+        }
+        else {
+            return some(ret);
+        }
+    }),
+    state_has.implement((key) => {
+        return store.has(key);
+    }),
+];
+/**
+ * Creates a typed state write function for a given key and type.
+ *
+ * @remarks
+ * Returns an East function that writes a typed value to state. The value is
+ * automatically Beast2-encoded before storage. Pass `some(value)` to write
+ * or `none` to delete the key.
+ *
+ * @typeParam T - The East type of the value to write
+ * @param key - The string key to write to
+ * @param value - The value wrapped in an option (some to write, none to delete)
+ * @param type - The East type descriptor for the value
+ * @returns A callable East function that performs the write
  *
  * @example
  * ```ts
- * const updateCount = East.function(
- *     [['state', DictType(StringType, BlobType)]],
- *     NullType,
- *     ($, state) => {
- *         const countBlob = state.get("count");
- *         const count = countBlob.decodeBeast(IntegerType);
- *         $(State.write("count", East.Blob.encodeBeast(count.add(1n))));
- *     }
- * );
+ * import { East, IntegerType, NullType, some } from "@elaraai/east";
+ * import { State, UIComponentType } from "@elaraai/east-ui";
+ *
+ * const counter = East.function([], UIComponentType, $ => {
+ *     // Write 42 to "counter" key
+ *     $(State.writeTyped("counter", some(42n), IntegerType)());
+ *
+ *     // Delete the key
+ *     $(State.writeTyped("counter", none, IntegerType)());
+ * });
  * ```
  */
-export const state_write = East.platform("state_write", [StringType, BlobType], NullType);
+export const state_write_typed = (key, value, type) => {
+    return East.function([], NullType, $ => {
+        const key_expr = East.value(key);
+        const value_expr = East.value(value, OptionType(type));
+        $.match(value_expr, {
+            some: ($, v) => {
+                $(state_write(key_expr, some(East.Blob.encodeBeast(v, "v2"))));
+            },
+            none: ($) => {
+                $(state_write(key_expr, none));
+            }
+        });
+        return null;
+    });
+};
 /**
- * Platform function to read a Beast2-encoded value from the state store.
- * Returns an empty blob if the key doesn't exist.
+ * Creates a typed state read function for a given key and type.
  *
- * This is a platform function for the East language, enabling state management
- * in East UI applications. The implementation is provided by the React store
- * in `@elaraai/east-ui-components`.
+ * @remarks
+ * Returns an East function that reads a typed value from state. The value is
+ * automatically Beast2-decoded after retrieval. Returns `some(value)` if the
+ * key exists, `none` if not.
  *
+ * @typeParam T - The East type of the value to read
  * @param key - The string key to read from
- * @returns The Beast2-encoded blob value
+ * @param type - The East type descriptor for the value
+ * @returns A callable East function that returns an option of the typed value
  *
  * @example
  * ```ts
- * const readCount = East.function([], IntegerType, ($) => {
- *     const blob = State.read("count");
- *     return blob.decodeBeast(IntegerType);
+ * import { East, IntegerType, NullType } from "@elaraai/east";
+ * import { State, UIComponentType, Text } from "@elaraai/east-ui";
+ *
+ * const display = East.function([], UIComponentType, $ => {
+ *     // Read typed value from state
+ *     const count = $.let(State.readTyped("counter", IntegerType)());
+ *
+ *     // Use the value (unwrap if you know it exists)
+ *     return Text.Root(East.str`Count: ${count.unwrap("some")}`);
  * });
  * ```
  */
-export const state_read = East.platform("state_read", [StringType], BlobType);
+export const state_read_typed = (key, type) => {
+    return East.function([], OptionType(type), $ => {
+        const key_expr = East.value(key);
+        const ret = $.let(none, OptionType(type));
+        $.match(state_read(key_expr), {
+            some: ($, v) => {
+                $.assign(ret, East.value(some(v.decodeBeast(type, "v2")), OptionType(type)));
+            },
+        });
+        return ret;
+    });
+};
 /**
- * Grouped state management platform functions.
+ * Creates a typed state initialization function that only writes if the key doesn't exist.
  *
- * Provides reactive state operations for East UI programs.
- * The implementation is created by the EastStore in `@elaraai/east-ui-components`.
+ * @remarks
+ * Returns an East function that initializes a state key with a default value.
+ * The write only occurs if the key is not already set, preventing overwrites
+ * on re-renders. Use this for setting up initial state in components.
+ *
+ * @typeParam T - The East type of the value to initialize
+ * @param key - The string key to initialize
+ * @param value - The default value to write (not wrapped in option)
+ * @param type - The East type descriptor for the value
+ * @returns A callable East function that performs the conditional initialization
  *
  * @example
  * ```ts
- * import { East, DictType, StringType, BlobType, IntegerType } from "@elaraai/east";
- * import { State } from "@elaraai/east-ui";
- * import { createEastStore } from "@elaraai/east-ui-components";
- *
- * const counter = East.function(
- *     [['state', DictType(StringType, BlobType)]],
- *     UIComponentType,
- *     ($, state) => {
- *         // Read current count
- *         const countBlob = state.get("count");
- *         const count = countBlob.decodeBeast(IntegerType);
- *
- *         // Write incremented count
- *         $(State.write("count", East.Blob.encodeBeast(count.add(1n))));
- *
- *         return Text.Root(East.str`Count: ${count}`);
- *     }
- * );
- *
- * // Create store and register function
- * const store = createEastStore();
- * store.register("counter", counter.toIR());
+ * import { East, IntegerType } from "@elaraai/east";
+ * import { State, UIComponentType, Button } from "@elaraai/east-ui";
+ *
+ * const counter = East.function([], UIComponentType, $ => {
+ *     // Initialize to 0 only if not already set
+ *     $(State.initTyped("counter", 0n, IntegerType)());
+ *
+ *     // Read and display
+ *     const count = $.let(State.readTyped("counter", IntegerType)());
+ *     // ...
+ * });
  * ```
  */
-export const State = {
-    /**
-     * Writes a Beast2-encoded value to the state store.
-     *
-     * @param key - The string key to write to
-     * @param value - The Beast2-encoded blob value
-     * @returns Null
-     */
-    write: state_write,
-    /**
-     * Reads a Beast2-encoded value from the state store.
-     * Returns an empty blob if the key doesn't exist.
-     *
-     * @param key - The string key to read from
-     * @returns The Beast2-encoded blob value
-     */
-    read: state_read,
+export const state_init_typed = (key, value, type) => {
+    return East.function([], NullType, $ => {
+        const key_expr = East.value(key);
+        const value_expr = East.value(value, type);
+        $.match(state_read(key_expr), {
+            none: ($) => {
+                $(state_write(key_expr, some(East.Blob.encodeBeast(value_expr, "v2"))));
+            },
+        });
+        return null;
+    });
 };
 //# sourceMappingURL=state.js.map

package/dist/src/platform/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/platform/state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,MAAM,WAAW,GACpB,IAAI,CAAC,QAAQ,CAAC,aAAa,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;AAEnE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,UAAU,GACnB,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACjB;;;;;;OAMG;IACH,KAAK,EAAE,WAAW;IAElB;;;;;;OAMG;IACH,IAAI,EAAE,UAAU;CACV,CAAC"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/platform/state.ts"],"names":[],"mappings":"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"}