@hypen-space/core 0.4.31 → 0.4.35

package/dist/datasource.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Data Source Plugin System for Hypen
+ *
+ * Enables live subscription databases (SpacetimeDB, Firebase, Convex, Electric SQL)
+ * to push data into the Hypen reactive engine via a unified plugin interface.
+ *
+ * UI bindings use the `$provider.path` syntax:
+ *   - `$spacetime.messages` → SpacetimeDB messages table
+ *   - `$firebase.user.profile` → Firebase user profile
+ *   - `$convex.tasks` → Convex tasks table
+ *
+ * @module
+ */
+/** Connection status for a data source provider */
+export type DataSourceStatus = "disconnected" | "connecting" | "connected" | "reconnecting" | "error";
+/** Describes a subscription to a table or query */
+export interface DataSourceQuery {
+    /** Table or collection name (e.g., "messages", "users") */
+    table: string;
+    /** Optional filter criteria */
+    filter?: Record<string, unknown>;
+    /** Optional raw query string (e.g., SQL for SpacetimeDB) */
+    sql?: string;
+}
+/** Handle returned by subscribe() — call unsubscribe() to stop receiving updates */
+export interface DataSourceSubscription {
+    /** Stop receiving updates for this subscription */
+    unsubscribe(): void;
+    /** Current subscription status */
+    status: "pending" | "applied" | "error";
+    /** Error details if status is "error" */
+    error?: Error;
+}
+/** Describes a batch of changes pushed by a plugin */
+export interface DataSourceChange {
+    /** Changed paths relative to the provider root (e.g., ["messages", "users"]) */
+    paths: string[];
+    /** New values at those paths */
+    values: Record<string, unknown>;
+}
+/**
+ * Interface that all data source plugins must implement.
+ *
+ * A plugin manages the connection lifecycle and translates database-specific
+ * events (row inserts, updates, deletes) into `DataSourceChange` objects that
+ * the Hypen engine can consume.
+ *
+ * @typeParam TConfig - Plugin-specific configuration type
+ *
+ * @example
+ * ```typescript
+ * class SpacetimeDBPlugin implements DataSourcePlugin<SpacetimeDBConfig> {
+ *   readonly name = "spacetime";
+ *   status: DataSourceStatus = "disconnected";
+ *
+ *   async connect(config: SpacetimeDBConfig, onChange: (change: DataSourceChange) => void) {
+ *     // Connect to SpacetimeDB, subscribe to tables, push changes via onChange
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+export interface DataSourcePlugin<TConfig = unknown> {
+    /** Unique provider name (e.g., "spacetime", "firebase", "convex") */
+    readonly name: string;
+    /** Current connection status */
+    status: DataSourceStatus;
+    /**
+     * Connect to the data source and begin pushing changes.
+     *
+     * @param config - Plugin-specific configuration
+     * @param onChange - Callback to push data changes into the engine.
+     *   The plugin MUST call this whenever subscribed data changes.
+     */
+    connect(config: TConfig, onChange: (change: DataSourceChange) => void): Promise<void>;
+    /**
+     * Subscribe to a specific table or query.
+     * Returns a handle to unsubscribe later.
+     */
+    subscribe(query: DataSourceQuery): DataSourceSubscription;
+    /**
+     * Call a remote procedure / reducer / mutation.
+     *
+     * @param method - Method name (e.g., "sendMessage" for SpacetimeDB reducer)
+     * @param args - Arguments to pass
+     * @returns The result from the remote call
+     */
+    call(method: string, ...args: unknown[]): Promise<unknown>;
+    /**
+     * Disconnect from the data source and clean up all subscriptions.
+     */
+    disconnect(): Promise<void>;
+}
+/** Interface for the engine's data source operations (maps to WASM setContext/removeContext) */
+export interface IDataSourceEngine {
+    /**
+     * Set (or replace) a named data source context.
+     * Registers the provider, stores the data, and re-renders bound nodes.
+     * Sparse merging should happen at the SDK layer before calling this.
+     */
+    setContext(name: string, data: Record<string, unknown>): void;
+    /**
+     * Remove a data source context entirely.
+     * Drops the provider's state and re-renders bound nodes (they resolve to null).
+     */
+    removeContext(name: string): void;
+}
+/**
+ * Manages data source plugin lifecycles and bridges them to the Hypen engine.
+ *
+ * The manager:
+ * 1. Registers plugins with the engine (creates state slots)
+ * 2. Connects plugins and wires their onChange callbacks to engine updates
+ * 3. Manages subscription lifecycles
+ * 4. Handles cleanup on disconnect
+ *
+ * @example
+ * ```typescript
+ * const manager = new DataSourceManager(engine);
+ *
+ * // Register and connect a SpacetimeDB plugin
+ * await manager.use(new SpacetimeDBPlugin(), {
+ *   uri: "ws://localhost:3000",
+ *   moduleName: "chat",
+ *   tables: ["user", "message"],
+ * });
+ *
+ * // Access plugin for mutations
+ * await manager.get("spacetime").call("sendMessage", "Hello!");
+ *
+ * // Clean up
+ * await manager.disconnectAll();
+ * ```
+ */
+export declare class DataSourceManager {
+    private plugins;
+    private configs;
+    /** Accumulated state per provider — sparse merging happens here before setContext */
+    private state;
+    private engine;
+    constructor(engine: IDataSourceEngine);
+    /**
+     * Register, connect, and start a data source plugin.
+     *
+     * @param plugin - The plugin instance
+     * @param config - Plugin-specific configuration
+     */
+    use<C>(plugin: DataSourcePlugin<C>, config: C): Promise<void>;
+    /**
+     * Get a registered plugin by name.
+     * Useful for calling mutations: `manager.get("spacetime").call("sendMessage", text)`
+     */
+    get<T extends DataSourcePlugin = DataSourcePlugin>(name: string): T | undefined;
+    /** Check if a plugin is registered */
+    has(name: string): boolean;
+    /** Get all registered provider names */
+    getNames(): string[];
+    /** Get the status of a specific plugin */
+    getStatus(name: string): DataSourceStatus | undefined;
+    /**
+     * Disconnect and remove a specific plugin.
+     */
+    remove(name: string): Promise<void>;
+    /**
+     * Disconnect all plugins and clean up.
+     */
+    disconnectAll(): Promise<void>;
+}

package/dist/discovery.js

@@ -1,12 +1,16 @@
 import { createRequire } from "node:module";
 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);
@@ -381,6 +385,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/state.ts
 function deepClone(obj) {
   if (obj === null || typeof obj !== "object") {
@@ -520,9 +577,11 @@ function createObservableState(initialState, options) {
           notificationPending = false;
           if (batchDepth === 0) {
             notifyChange();
-          }
+          } else {}
         });
       }
+    } else {
+      pendingChange = pendingChange || { paths: [], newValues: {} };
     }
   }
   const proxyCache = new WeakMap;
@@ -581,11 +640,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);
@@ -650,6 +710,7 @@ class HypenAppBuilder {
   errorHandler;
   template;
   _registry;
+  dataSourceEntries = [];
   constructor(initialState, options, registry) {
     this.initialState = initialState;
     this.options = options || {};
@@ -683,10 +744,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 = __require("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 = {
@@ -697,6 +767,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,
@@ -758,6 +829,8 @@ class HypenModuleInstance {
   router;
   globalContext;
   stateChangeCallbacks = [];
+  dataSourceManager;
+  dataSourceAccessor = {};
   constructor(engine, definition, router, globalContext) {
     this.engine = engine;
     this.definition = definition;
@@ -787,7 +860,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 });
@@ -830,8 +904,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;
   }
@@ -878,6 +953,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 {
@@ -897,6 +991,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);
@@ -1059,6 +1162,8 @@ async function discoverComponents(baseDir, options = {}) {
           const module = moduleExport.default;
           if (module && typeof module === "object" && module.template) {
             addSingleFileComponent(baseName, modulePath, module.template);
+          } else if (module && typeof module === "object") {
+            frameworkLoggers.discovery.warn(`Skipping "${entry.name}": has .ui() pattern but module has no .template property. Did you forget to call .ui(hypen\`...\`)?`);
           }
         } catch (e) {
           log3(`Failed to import potential single-file component: ${entry.name}`, e);
@@ -1226,4 +1331,4 @@ export {
   discoverComponents
 };
 
-//# debugId=46EBEA75EF219F3964756E2164756E21
+//# debugId=D8CFBCA4D5F7D1BB64756E2164756E21