@igojs/signal 6.0.0-beta.1

package/src/client/StateProxy.js

@@ -0,0 +1,74 @@
+/**
+ * StateProxy - Deep reactive state with Proxy (like Vue 3)
+ *
+ * Features:
+ * - Deep reactivity (nested objects/arrays)
+ * - Array mutation detection (push, pop, splice, etc.)
+ * - WeakMap caching to avoid double-wrapping
+ */
+class StateProxy {
+  constructor(component, namespace) {
+    this.component = component;
+    this.namespace = namespace;
+    this.cache = new WeakMap();
+  }
+
+  create(target, path = []) {
+    if (this.cache.has(target)) return this.cache.get(target);
+
+    const proxy = new Proxy(target, {
+      get: (target, property) => {
+        // Track dependency
+        if (this.component._isTracking) {
+          this.component._trackedDeps.push([this.namespace, ...path, property]);
+        }
+
+        const value = target[property];
+
+        // Don't wrap primitives, functions, Date, RegExp
+        if (!value || typeof value !== 'object' || value instanceof Date || value instanceof RegExp) {
+          return value;
+        }
+
+        // Recursively wrap objects/arrays
+        return this.create(value, [...path, property]);
+      },
+
+      set: (target, property, value) => {
+        const oldValue = target[property];
+        target[property] = value;
+
+        // Trigger render if changed
+        if (this.component._isInitialized && !Object.is(oldValue, value)) {
+          this.component._triggerRender();
+        }
+
+        return true;
+      }
+    });
+
+    // Wrap array methods
+    if (Array.isArray(target)) {
+      ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'].forEach(method => {
+        const original = Array.prototype[method];
+        Object.defineProperty(target, method, {
+          value: (...args) => {
+            const result = original.apply(target, args);
+            if (this.component._isInitialized) this.component._triggerRender();
+            return result;
+          },
+          enumerable: false,
+          writable: true,
+          configurable: true
+        });
+      });
+    }
+
+    this.cache.set(target, proxy);
+    return proxy;
+  }
+
+
+}
+
+module.exports = StateProxy;

package/src/client/dust/Templates.js

@@ -0,0 +1,26 @@
+
+const _CACHE = {};
+
+const AsyncFunction = Object.getPrototypeOf(async function() { }).constructor;
+
+const getTemplate = (file) => {
+  // loadTemplate(file);
+  return _CACHE[file];
+};
+
+const loadTemplate = async (file) => {
+  if (!_CACHE[file]) {
+    const response  = await fetch(`/__signal/templates?file=${file}`);
+    const json      = await response.json();
+    // console.dir(json);
+    const fn        = new AsyncFunction('l', 'u', 'c', 's', json.source);
+    _CACHE[file]    = fn;
+  }
+  return _CACHE[file];
+};
+
+module.exports = {
+  getTemplate,
+  loadTemplate,
+  _CACHE
+};

package/src/client/dust/Utils.js

@@ -0,0 +1,124 @@
+const Templates        = require('./Templates');
+const { uneval }       = require('devalue'); // Bundler handles ES modules correctly
+const igoDustHelpers   = require('@igojs/dust/src/render/Helpers');
+const { createSerializeHelper, htmlencode } = require('../../shared/serialize');
+
+// Special characters
+const BS      = /\\/g,
+  LS      = /\u2028/g,
+  PS      = /\u2029/g,
+  LT      = /</g,
+  FS      = /\//g,
+  CR      = /\r/g,
+  NL      = /\n/g,
+  LF      = /\f/g,
+  SQ      = /'/g,
+  DQ      = /"/g,
+  TB      = /\t/g;
+
+const escapeJs = (s) => {
+  if (typeof s === 'string') {
+    return s
+    .replace(BS, '\\\\')
+    .replace(FS, '\\/')
+    .replace(DQ, '\\"')
+    .replace(SQ, '\\\'')
+    .replace(CR, '\\r')
+    .replace(LS, '\\u2028')
+    .replace(PS, '\\u2029')
+    .replace(NL, '\\n')
+    .replace(LF, '\\f')
+    .replace(TB, '\\t');
+  }
+  return s;
+};
+
+const stringifyJson = (o) => {
+  return o && JSON.stringify(o)
+  .replace(LS, '\\u2028')
+  .replace(PS, '\\u2029')
+  .replace(LT, '\\u003c');
+};
+
+// Filters
+const f = {
+  h:          htmlencode,
+  j:          escapeJs,
+  u:          encodeURI,
+  uc:         encodeURIComponent,
+  js:         stringifyJson,
+  jp:         JSON.parse,
+  uppercase:  s => s.toUpperCase(),
+  lowercase:  s => s.toLowerCase(),
+};
+
+
+// return value to be displayed
+const d = (s, t, l) => {
+  if (typeof s === 'function') {
+    return s.call(t, l);
+  }
+  if (s === null || s === undefined) {
+    return '';
+  }
+  return s;
+};
+
+// return value (if it's a function, invoke it with locals)
+const v = (s, t, l) => {
+  if (typeof s === 'function') {
+    return s.call(t, l);
+  }
+  return s;
+};
+
+// return boolean
+const b = (v) => {
+  if (!v) {
+    return false;
+  }
+  if (v.length === 0) {
+    return false;
+  }
+  return true;
+};
+
+// return array
+const a = (v) => {
+  if (Array.isArray(v)) {
+    if (v.length === 0) {
+      return null;
+    }
+    return v;
+  }
+  if (v) {
+    return [v];
+  }
+  return null;
+};
+
+// helpers
+const h = (t, p, l) => {
+  if (!h.helpers || !h.helpers[t]) {
+    throw new Error(`Error: helper @${t} not found!`);
+  }
+  return h.helpers[t](p, l);
+};
+
+// Initialize with igo-dust base helpers
+h.helpers = {
+  ...igoDustHelpers,
+  serialize: createSerializeHelper(uneval)
+};
+
+// Register application helpers (called by signal.start())
+const setHelpers = (appHelpers) => {
+  Object.assign(h.helpers, appHelpers);
+};
+
+// include file
+const i = async (file) => {
+  return await Templates.loadTemplate(file);
+};
+
+module.exports = { a, b, v, d, h, f, i, setHelpers };

package/src/client/dust/i18n.js

@@ -0,0 +1,22 @@
+const i18next = require('i18next');
+
+// Get language from <html lang="..."> attribute (set by server)
+const lang = document.documentElement.lang || 'en';
+
+// Initialize i18next with translations injected from the server
+i18next.init({
+  lng: lang,
+  fallbackLng: 'en',
+  resources: {
+    [lang]: {
+      translation: window.__signal_translations || {}
+    }
+  },
+  interpolation: {
+    escapeValue: false
+  }
+});
+
+// Expose globally for use in components
+window.i18next = i18next;
+

package/src/client/index.js

@@ -0,0 +1,72 @@
+/**
+ * Signal - Zero-boilerplate reactive framework (browser entry point)
+ *
+ * Usage:
+ *   require('@igojs/signal/src/client').start({
+ *     components: { 'Counter': Counter },
+ *     helpers: require('./helpers')
+ *   });
+ */
+
+require('./dust/i18n');
+
+const SignalComponent = require('./SignalComponent');
+const Utils = require('./dust/Utils');
+
+window.__signal = {
+  IgoDustUtils: Utils
+};
+
+let registry = {};
+
+function mountElement(el) {
+  if (el.__igoInstance) {
+    return;
+  }
+  const Comp = registry[el.dataset.component];
+  if (Comp) {
+    new Comp(el);
+  } else {
+    console.error(`[signal] Component "${el.dataset.component}" not found`);
+  }
+}
+
+function mountAll(root = document) {
+  root.querySelectorAll('[data-component]').forEach(mountElement);
+}
+
+function start(config = {}) {
+  const { components, helpers } = config;
+
+  // Register application helpers
+  if (helpers) {
+    Utils.setHelpers(helpers);
+  }
+
+  // Build component registry
+  if (components) {
+    // Support webpack require.context
+    if (typeof components.keys === 'function') {
+      components.keys().forEach(key => {
+        const mod = components(key);
+        if (mod?.prototype instanceof SignalComponent) {
+          registry[key.replace(/^\.\//, '').replace(/\.js$/, '')] = mod;
+        }
+      });
+    } else {
+      // Support plain object { 'path': ComponentClass }
+      Object.assign(registry, components);
+    }
+  }
+
+  // Mount components
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => mountAll());
+  } else {
+    mountAll();
+  }
+}
+
+window.__signal.mountElement = mountElement;
+
+module.exports = { SignalComponent, start, mountAll, mountElement };

package/src/server/SerializeUtils.js

@@ -0,0 +1,70 @@
+
+const _ = require('lodash');
+
+/**
+ * Serialize data for client-side hydration
+ *
+ * This function prepares data for devalue by converting Model instances
+ * to plain objects using their serialize() method.
+ *
+ * IMPORTANT: For deduplication to work, pass the same object references
+ * multiple times. Do NOT create separate serialize() calls before passing
+ * to this function - let it handle the serialization.
+ *
+ * @param {any} data - Data to serialize
+ * @param {WeakMap} [seen] - Internal map for tracking already-serialized objects
+ * @returns {any} - Serialized data ready for devalue
+ */
+module.exports.serialize = (data, seen = new WeakMap()) => {
+  if (data === null || data === undefined) {
+    return null;
+  }
+  // Skip functions
+  if (_.isFunction(data)) {
+    return undefined;
+  }
+  // Keep Date objects as-is (devalue handles them natively)
+  if (_.isDate(data)) {
+    return data;
+  }
+  if (_.isArray(data)) {
+    return _.map(data, item => module.exports.serialize(item, seen));
+  }
+  // Model instances with serialize method
+  if (_.isFunction(data?.serialize)) {
+    // Check if already serialized (deduplication)
+    if (seen.has(data)) {
+      return seen.get(data);
+    }
+    // Create placeholder to handle circular refs
+    const serialized = {};
+    seen.set(data, serialized);
+    // Serialize and merge into placeholder
+    const result = data.serialize();
+    Object.assign(serialized, module.exports.serialize(result, seen));
+    return serialized;
+  }
+  // Form instances with getValues method (Igo Form)
+  if (_.isFunction(data?.getValues) && data.constructor?.schema?.attributes) {
+    return module.exports.serialize(data.getValues(), seen);
+  }
+  // Plain objects only - recursively serialize values
+  if (_.isPlainObject(data)) {
+    // Check if already processed (for circular plain objects)
+    if (seen.has(data)) {
+      return seen.get(data);
+    }
+    const serialized = {};
+    seen.set(data, serialized);
+    for (const [key, value] of Object.entries(data)) {
+      serialized[key] = module.exports.serialize(value, seen);
+    }
+    return serialized;
+  }
+  // Primitives (string, number, boolean)
+  if (!_.isObject(data)) {
+    return data;
+  }
+  // Skip non-POJO class instances that we don't know how to serialize
+  return undefined;
+};

package/src/server/SignalController.js

@@ -0,0 +1,94 @@
+
+const { dust: IgoDust } = require('@igojs/server');
+
+const SerializeUtils  = require('./SerializeUtils');
+const { createSerializeHelper } = require('../shared/serialize');
+
+// Load devalue dynamically (ES module)
+let uneval;
+let helperRegistered = false;
+const devaluePromise = import('devalue').then(mod => {
+  uneval = mod.uneval;
+});
+
+// Translations are loaded from user's project (configured via signal.configure())
+let translations = {};
+
+// Register @serialize helper (called once after devalue is loaded)
+const registerHelper = () => {
+  if (helperRegistered) return;
+  helperRegistered = true;
+  IgoDust.helpers.serialize = createSerializeHelper(uneval);
+};
+
+
+/**
+ * Signal middleware - Handles SSR for SignalComponents
+ *
+ * Usage in controllers:
+ *   res.locals.signal_props = { session, products, form, ... };
+ *   res.locals.signal_components = [NewRegistrationForm];  // optional: for SSR derived values
+ *   res.render('view');
+ *
+ * The middleware will:
+ * 1. Serialize signal_props with deduplication (Model.serialize() called once per instance)
+ * 2. Compute SSR derived values from registered signal_components
+ * 3. Merge everything into res.locals for template rendering
+ */
+module.exports.middleware = async (req, res, next) => {
+
+  // Wait for devalue to be loaded, then register helper
+  await devaluePromise;
+  registerHelper();
+
+  // Inject translations for frontend i18next
+  res.locals.__signal_translations = uneval(translations);
+
+  const originalRender = res.render.bind(res);
+
+  res.render = (view, locals, callback) => {
+    const props = locals?.signal_props || res.locals.signal_props || {};
+    const components = res.locals.signal_components || [];
+
+    try {
+      // Serialize props with deduplication
+      const serializedProps = SerializeUtils.serialize(props);
+
+      // Store serialized props for client hydration (devalue for XSS safety)
+      res.locals.__signal_props = uneval(serializedProps);
+
+      // Merge raw props into res.locals for template access
+      Object.assign(res.locals, props);
+
+      // Compute and merge SSR derived values from each component
+      for (const ComponentClass of components) {
+        if (ComponentClass?.ssr) {
+          const derived = ComponentClass.ssr(props);
+          Object.assign(res.locals, derived);
+        }
+      }
+
+    } catch (error) {
+      console.error('[Signal] Serialization error:', error);
+      res.locals.__signal_props = '{}';
+    }
+
+    return originalRender(view, locals, callback);
+  };
+
+  next();
+};
+
+//
+module.exports.templates = async (req, res) => {
+  const file = req.query.file;
+  const source = await IgoDust.getSource(`${file}.dust`);
+  res.json({ file, source });
+};
+
+// Configure Signal (called from user's app)
+module.exports.configure = (options) => {
+  if (options.translations) {
+    translations = options.translations;
+  }
+};

package/src/server/index.js

@@ -0,0 +1,17 @@
+/**
+ * Signal - Server-side SSR support for SignalComponents
+ *
+ * This module provides:
+ * - SignalController: Express middleware for SSR and template serving
+ * - SerializeUtils: Model serialization with deduplication
+ */
+
+const SignalController = require('./SignalController');
+const SerializeUtils = require('./SerializeUtils');
+
+module.exports = {
+  middleware: SignalController.middleware,
+  templates: SignalController.templates,
+  configure: SignalController.configure,
+  serialize: SerializeUtils.serialize
+};

package/src/shared/serialize.js

@@ -0,0 +1,35 @@
+
+// Shared serialize helper for @igojs/signal
+// Used both server-side (SignalController) and client-side (Utils)
+
+const HCHARS = /[&<>"']/;
+
+const htmlencode = (s) => {
+  if (!s || typeof s !== 'string' || !HCHARS.test(s)) {
+    return s;
+  }
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+};
+
+/**
+ * Create serialize helper function with the provided uneval function
+ * @param {Function} uneval - The uneval function from devalue
+ * @returns {Function} The serialize helper
+ */
+const createSerializeHelper = (uneval) => {
+  return (params, locals) => {
+    const data = {};
+    const keys = (params.props || '').split(',').map(p => p.trim()).filter(Boolean);
+    keys.forEach(key => {
+      data[key] = locals[key];
+    });
+    return htmlencode(uneval(data));
+  };
+};
+
+module.exports = { createSerializeHelper, htmlencode };

package/test/client/DerivedCacheTest.js

@@ -0,0 +1,44 @@
+const assert = require('assert');
+const DerivedCache = require('../../src/client/DerivedCache');
+
+describe('DerivedCache', () => {
+
+  it('should cache computed values', () => {
+    const cache = new DerivedCache();
+    const context = { props: { value: 1 }, state: {} };
+    let callCount = 0;
+
+    const fn = () => ++callCount;
+
+    cache.memoize('test', fn, [], context, fn());
+    cache.memoize('test', fn, [], context);
+
+    assert.strictEqual(callCount, 1);
+  });
+
+  it('should recompute when deps change', () => {
+    const cache = new DerivedCache();
+    const context = { props: { count: 1 }, state: {} };
+
+    const fn = () => context.props.count * 2;
+
+    cache.memoize('double', fn, [['props', 'count']], context, fn());
+    context.props.count = 5;
+    const result = cache.memoize('double', fn, [['props', 'count']], context);
+
+    assert.strictEqual(result, 10);
+  });
+
+  it('should clear all cached values', () => {
+    const cache = new DerivedCache();
+    let count = 0;
+    const fn = () => ++count;
+
+    cache.memoize('a', fn, [], {}, fn());
+    cache.clear();
+    cache.memoize('a', fn, [], {});
+
+    assert.strictEqual(count, 2);
+  });
+
+});

package/test/client/SignalComponentTest.js

@@ -0,0 +1,59 @@
+const assert = require('assert');
+const SignalComponent = require('../../src/client/SignalComponent');
+
+describe('SignalComponent', () => {
+
+  it('should initialize with props in SSR mode', () => {
+    const props = { products: [{ id: 1 }] };
+    const component = new SignalComponent(null, 'test', props);
+
+    assert.deepStrictEqual(component.props, props);
+  });
+
+  it('should initialize form state from props.form', () => {
+    const props = { form: { search: 'test' } };
+    const component = new SignalComponent(null, 'test', props);
+
+    assert.deepStrictEqual(component._state.form, props.form);
+  });
+
+  it('should compute derived values via ssr()', () => {
+    class TestComponent extends SignalComponent {
+      get doubled() {
+        return (this.props.value || 0) * 2;
+      }
+    }
+
+    const derived = TestComponent.ssr({ value: 5 });
+
+    assert.strictEqual(derived.doubled, 10);
+  });
+
+  it('should skip private and reserved getters in ssr()', () => {
+    class TestComponent extends SignalComponent {
+      get _private() { return 'hidden'; }
+      get public() { return 'visible'; }
+    }
+
+    const derived = TestComponent.ssr({});
+
+    assert.strictEqual(derived._private, undefined);
+    assert.strictEqual(derived.public, 'visible');
+  });
+
+  it('should handle getter errors gracefully in ssr()', () => {
+    class TestComponent extends SignalComponent {
+      get failing() { throw new Error('DOM error'); }
+      get working() { return 'ok'; }
+    }
+
+    const originalError = console.error;
+    console.error = () => {};
+    const derived = TestComponent.ssr({});
+    console.error = originalError;
+
+    assert.strictEqual(derived.failing, undefined);
+    assert.strictEqual(derived.working, 'ok');
+  });
+
+});

package/test/client/StateProxyTest.js

@@ -0,0 +1,59 @@
+const assert = require('assert');
+const StateProxy = require('../../src/client/StateProxy');
+
+describe('StateProxy', () => {
+
+  function createMockComponent() {
+    return {
+      _isTracking: false,
+      _trackedDeps: [],
+      _isInitialized: true,
+      _renderCount: 0,
+      _triggerRender() { this._renderCount++; }
+    };
+  }
+
+  it('should trigger render on property change', () => {
+    const component = createMockComponent();
+    const state = new StateProxy(component, 'state').create({ count: 0 });
+
+    state.count = 5;
+
+    assert.strictEqual(state.count, 5);
+    assert.strictEqual(component._renderCount, 1);
+  });
+
+  it('should handle nested objects', () => {
+    const component = createMockComponent();
+    const state = new StateProxy(component, 'state').create({
+      user: { name: 'John' }
+    });
+
+    state.user.name = 'Jane';
+
+    assert.strictEqual(state.user.name, 'Jane');
+    assert.strictEqual(component._renderCount, 1);
+  });
+
+  it('should trigger render on array methods', () => {
+    const component = createMockComponent();
+    const state = new StateProxy(component, 'state').create({ items: [] });
+
+    state.items.push({ id: 1 });
+
+    assert.strictEqual(state.items.length, 1);
+    assert.strictEqual(component._renderCount, 1);
+  });
+
+  it('should track dependencies when tracking is enabled', () => {
+    const component = createMockComponent();
+    const state = new StateProxy(component, 'state').create({ count: 0 });
+
+    component._isTracking = true;
+    const _ = state.count;
+    component._isTracking = false;
+
+    assert.deepStrictEqual(component._trackedDeps[0], ['state', 'count']);
+  });
+
+});