@hypen-space/core 0.4.31 → 0.4.35

package/dist/app.d.ts

@@ -5,6 +5,7 @@
 import type { Action } from "./types.js";
 import type { Session } from "./remote/types.js";
 import { HypenError } from "./result.js";
+import { type DataSourcePlugin } from "./datasource.js";
 export interface IEngine {
     setModule(name: string, actions: string[], stateKeys: string[], initialState: unknown): void;
     onAction(actionName: string, handler: (action: Action) => void | Promise<void>): void;
@@ -34,6 +35,19 @@ export interface ActionHandlerContext<T, P = unknown> {
     action: ActionContext<P>;
     state: T;
     context: GlobalContext;
+    /** Access to registered data source plugins for mutations */
+    dataSources: DataSourceAccessor;
+}
+/**
+ * Provides typed access to registered data source plugins.
+ * Unknown method calls are forwarded to `plugin.call()`:
+ *   `dataSources.spacetime.sendMessage(text)` → `plugin.call("sendMessage", text)`
+ *
+ * You can also call `.call()` directly if you prefer:
+ *   `dataSources.spacetime.call("sendMessage", text)`
+ */
+export interface DataSourceAccessor {
+    [providerName: string]: DataSourcePlugin & Record<string, (...args: unknown[]) => Promise<unknown>>;
 }
 /**
  * Action handler - receives all context in a single object
@@ -115,6 +129,14 @@ export interface HypenModuleDefinition<T = unknown> {
      * Set via the `.ui(hypen`...`)` method.
      */
     template?: string;
+    /**
+     * Data source plugins registered via `.useDataSource()`.
+     * Each entry contains the plugin and its configuration.
+     */
+    dataSources?: Array<{
+        plugin: DataSourcePlugin;
+        config: unknown;
+    }>;
     handlers: {
         onCreated?: LifecycleHandler<T>;
         onAction: Map<string, ActionHandler<T, any>>;
@@ -148,6 +170,7 @@ export declare class HypenAppBuilder<T> {
     private errorHandler?;
     private template?;
     private _registry?;
+    private dataSourceEntries;
     constructor(initialState: T, options?: {
         persist?: boolean;
         version?: number;
@@ -225,6 +248,35 @@ export declare class HypenAppBuilder<T> {
      * @returns Builder for chaining
      */
     onError(fn: ErrorHandler<T>): this;
+    /**
+     * Register a data source plugin for live database subscriptions.
+     *
+     * @example
+     * ```typescript
+     * import { SpacetimeDBPlugin } from "@hypen-space/plugin-spacetimedb";
+     *
+     * export default app
+     *   .defineState({ messageText: "" })
+     *   .useDataSource(new SpacetimeDBPlugin(), {
+     *     uri: "ws://localhost:3000",
+     *     moduleName: "chat",
+     *     tables: ["user", "message"],
+     *   })
+     *   .onAction("sendMessage", async ({ state, dataSources }) => {
+     *     await dataSources.spacetime.sendMessage(state.messageText);
+     *     state.messageText = "";
+     *   })
+     *   .build();
+     * ```
+     *
+     * In Hypen DSL, bind to data source tables with `$provider.table`:
+     * ```hypen
+     * ForEach(items: $spacetime.message, key: "id") {
+     *   Text("${item.text}")
+     * }
+     * ```
+     */
+    useDataSource<C>(plugin: DataSourcePlugin<C>, config: C): this;
     /**
      * Define the component's UI template inline (single-file component).
      *
@@ -252,6 +304,23 @@ export declare class HypenAppBuilder<T> {
      * @returns The built module definition (calls build() internally)
      */
     ui(template: string): HypenModuleDefinition<T>;
+    /**
+     * Load a UI template from a .hypen file on disk.
+     *
+     * @example
+     * ```typescript
+     * import { app } from "@hypen-space/core";
+     *
+     * export default app
+     *   .defineState({ count: 0 })
+     *   .onAction("increment", ({ state }) => { state.count += 1; })
+     *   .uiFile("./counter.hypen");
+     * ```
+     *
+     * @param path - Path to a .hypen template file
+     * @returns The built module definition (calls build() internally)
+     */
+    uiFile(path: string): HypenModuleDefinition<T>;
     /**
      * Build the module definition
      */
@@ -336,6 +405,8 @@ export declare class HypenModuleInstance<T extends object = any> {
     private router;
     private globalContext?;
     private stateChangeCallbacks;
+    private dataSourceManager?;
+    private dataSourceAccessor;
     constructor(engine: IEngine, definition: HypenModuleDefinition<T>, router?: HypenRouter | null, globalContext?: HypenGlobalContext);
     /**
      * Create the global context API for this module
@@ -353,7 +424,7 @@ export declare class HypenModuleInstance<T extends object = any> {
      */
     private handleError;
     /**
-     * Call the onCreated handler
+     * Call the onCreated handler and connect data source plugins
      */
     private callCreatedHandler;
     /**
@@ -361,7 +432,7 @@ export declare class HypenModuleInstance<T extends object = any> {
      */
     onStateChange(callback: () => void): void;
     /**
-     * Destroy the module instance
+     * Destroy the module instance and disconnect all data source plugins
      */
     destroy(): Promise<void>;
     /**

package/dist/app.js

@@ -1,11 +1,15 @@
 var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -156,9 +160,11 @@ function createObservableState(initialState, options) {
           notificationPending = false;
           if (batchDepth === 0) {
             notifyChange();
-          }
+          } else {}
         });
       }
+    } else {
+      pendingChange = pendingChange || { paths: [], newValues: {} };
     }
   }
   const proxyCache = new WeakMap;
@@ -217,11 +223,12 @@ function createObservableState(initialState, options) {
         return true;
       },
       deleteProperty(obj, prop) {
-        if (prop in obj) {
-          delete obj[prop];
+        const existed = Object.prototype.hasOwnProperty.call(obj, prop);
+        const result = delete obj[prop];
+        if (existed) {
           scheduleBatch();
         }
-        return true;
+        return result;
       }
     });
     proxyCache.set(target, proxy);
@@ -555,6 +562,59 @@ var init_result = __esm(() => {
   };
 });
 
+// src/datasource.ts
+class DataSourceManager {
+  plugins = new Map;
+  configs = new Map;
+  state = new Map;
+  engine;
+  constructor(engine) {
+    this.engine = engine;
+  }
+  async use(plugin, config2) {
+    const { name } = plugin;
+    this.state.set(name, {});
+    this.plugins.set(name, plugin);
+    this.configs.set(name, config2);
+    await plugin.connect(config2, (change) => {
+      const current = this.state.get(name) ?? {};
+      for (const path of change.paths) {
+        if (path in change.values) {
+          current[path] = change.values[path];
+        }
+      }
+      this.state.set(name, current);
+      this.engine.setContext(name, current);
+    });
+  }
+  get(name) {
+    return this.plugins.get(name);
+  }
+  has(name) {
+    return this.plugins.has(name);
+  }
+  getNames() {
+    return Array.from(this.plugins.keys());
+  }
+  getStatus(name) {
+    return this.plugins.get(name)?.status;
+  }
+  async remove(name) {
+    const plugin = this.plugins.get(name);
+    if (plugin) {
+      await plugin.disconnect();
+      this.plugins.delete(name);
+      this.configs.delete(name);
+      this.state.delete(name);
+      this.engine.removeContext(name);
+    }
+  }
+  async disconnectAll() {
+    const names = Array.from(this.plugins.keys());
+    await Promise.all(names.map((name) => this.remove(name)));
+  }
+}
+
 // src/app.ts
 var exports_app = {};
 __export(exports_app, {
@@ -576,6 +636,7 @@ class HypenAppBuilder {
   errorHandler;
   template;
   _registry;
+  dataSourceEntries = [];
   constructor(initialState, options, registry) {
     this.initialState = initialState;
     this.options = options || {};
@@ -609,10 +670,19 @@ class HypenAppBuilder {
     this.errorHandler = fn;
     return this;
   }
+  useDataSource(plugin, config2) {
+    this.dataSourceEntries.push({ plugin, config: config2 });
+    return this;
+  }
   ui(template) {
     this.template = template;
     return this.build();
   }
+  uiFile(path) {
+    const fs = (() => ({}));
+    this.template = fs.readFileSync(path, "utf-8").trim();
+    return this.build();
+  }
   build() {
     const stateKeys = this.initialState !== null && typeof this.initialState === "object" ? Object.keys(this.initialState) : [];
     const definition = {
@@ -623,6 +693,7 @@ class HypenAppBuilder {
       version: this.options.version,
       initialState: this.initialState,
       template: this.template,
+      dataSources: this.dataSourceEntries.length > 0 ? this.dataSourceEntries : undefined,
       handlers: {
         onCreated: this.createdHandler,
         onAction: this.actionHandlers,
@@ -684,6 +755,8 @@ class HypenModuleInstance {
   router;
   globalContext;
   stateChangeCallbacks = [];
+  dataSourceManager;
+  dataSourceAccessor = {};
   constructor(engine, definition, router, globalContext) {
     this.engine = engine;
     this.definition = definition;
@@ -713,7 +786,8 @@ class HypenModuleInstance {
         const result = await this.executeAction(actionName, handler, {
           action: actionCtx,
           state: this.state,
-          context
+          context,
+          dataSources: this.dataSourceAccessor
         });
         if (!result.ok) {
           const shouldRethrow = await this.handleError(result.error, { actionName });
@@ -756,8 +830,9 @@ class HypenModuleInstance {
       on: (event, handler) => ctx.on(event, handler),
       router: this.router
     };
-    if (ctx.__hypenEngine) {
-      api.__hypenEngine = ctx.__hypenEngine;
+    const ctxRecord = ctx;
+    if (ctxRecord.__hypenEngine) {
+      api.__hypenEngine = ctxRecord.__hypenEngine;
     }
     return api;
   }
@@ -804,6 +879,25 @@ class HypenModuleInstance {
     return false;
   }
   async callCreatedHandler() {
+    if (this.definition.dataSources?.length) {
+      const dsEngine = this.engine;
+      this.dataSourceManager = new DataSourceManager(dsEngine);
+      for (const { plugin, config: config2 } of this.definition.dataSources) {
+        try {
+          await this.dataSourceManager.use(plugin, config2);
+          this.dataSourceAccessor[plugin.name] = new Proxy(plugin, {
+            get(target, prop) {
+              if (typeof prop === "string" && !(prop in target)) {
+                return (...args) => target.call(prop, ...args);
+              }
+              return target[prop];
+            }
+          });
+        } catch (e) {
+          log2.error(`Failed to connect data source "${plugin.name}":`, e);
+        }
+      }
+    }
     if (this.definition.handlers.onCreated) {
       const context = this.globalContext ? this.createGlobalContextAPI() : undefined;
       try {
@@ -823,6 +917,15 @@ class HypenModuleInstance {
   async destroy() {
     if (this.isDestroyed)
       return;
+    if (this.dataSourceManager) {
+      try {
+        await this.dataSourceManager.disconnectAll();
+      } catch (e) {
+        log2.error("Error disconnecting data sources:", e);
+      }
+      this.dataSourceManager = undefined;
+      this.dataSourceAccessor = {};
+    }
     if (this.definition.handlers.onDestroyed) {
       try {
         await this.definition.handlers.onDestroyed(this.state);
@@ -863,4 +966,4 @@ export {
   HypenApp
 };
 
-//# debugId=CCD1FE55458A9C0764756E2164756E21
+//# debugId=DF0AC5B74AEC489464756E2164756E21