@signaltree/core 4.0.16 → 4.1.1

package/LICENSE

@@ -0,0 +1,54 @@
+BUSINESS SOURCE LICENSE 1.1
+
+Copyright (c) 2025 Jonathan D Borgia
+
+This Business Source License 1.1 ("License") governs the use of the software and associated documentation files (the "Software"). You are granted a limited license to use the Software under the terms of this License.
+
+1. Definitions
+
+"Change Date" means the date on which the Change License set out in section 6 will apply to the Software. The Change Date for this release is 2028-09-05.
+
+"Change License" means the open source license that will apply to the Software on and after the Change Date. The Change License for this release is the MIT License.
+
+"Licensor" means the copyright owner granting rights under this License (Jonathan D Borgia).
+
+"You" ("Licensee") means an individual or legal entity exercising rights under this License who has not violated the terms of this License or had their rights terminated.
+
+2. License Grant
+
+Subject to the terms and conditions of this License, Licensor hereby grants You a non-exclusive, non-transferable, worldwide license to use, reproduce, display, perform, and distribute the Software, and to make modifications and derivative works for internal use, until the Change Date.
+
+3. Commercial Use
+
+You may use the Software in commercial applications, including for providing services, selling products that include the Software, or otherwise exploiting the Software commercially, subject to the other terms of this License.
+
+4. Limitations and Conditions
+
+a. You may not remove or alter this License, the copyright notice, or notices of the Change Date.
+
+b. You may not publicly offer a modified version of the Software that would directly compete with Licensor's public offering of the Software if doing so would circumvent the intent of this License.
+
+c. Except as expressly provided in this License, no rights are granted to You under any patent or trademark of Licensor.
+
+5. Disclaimer and Limitation of Liability
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. TO THE FULLEST EXTENT PERMITTED BY LAW, LICENSOR WILL NOT BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM OR RELATING TO THE SOFTWARE.
+
+6. Change License
+
+On and after the Change Date specified above, the Software will be licensed under the Change License (MIT License) on the same terms and conditions as set forth by that Change License.
+
+7. Governing Law
+
+This License will be governed by and construed in accordance with the laws of the State of New York, USA, without regard to conflict of law principles.
+
+8. Accepting this License
+
+You accept this License by copying, modifying, or distributing the Software or any portion thereof.
+
+---
+
+LICENSE NOTE
+
+- Original license file replaced on 2025-09-05 to Business Source License 1.1. Change Date: 2028-09-05. Change License: MIT.
+  or standard modifications for your own applications.

package/README.md

@@ -17,6 +17,33 @@ SignalTree Core is a lightweight package that provides:
 - Small API surface with zero-cost abstractions
 - Compact bundle size suited for production
 
+## Import guidance (tree-shaking)
+
+Modern bundlers (webpack 5+, esbuild, Rollup, Vite) **automatically tree-shake barrel imports** from `@signaltree/core`. Both import styles produce identical bundle sizes:
+
+```ts
+// ✅ Recommended: Simple and clean
+import { signalTree, withBatching } from '@signaltree/core';
+
+// ✅ Also fine: Explicit subpath (same bundle size)
+import { signalTree } from '@signaltree/core';
+import { withBatching } from '@signaltree/core/enhancers/batching';
+```
+
+**Measured impact** (with modern bundlers):
+
+- Core only: ~8.5 KB gzipped
+- Core + batching: ~9.3 KB gzipped (barrel vs subpath: identical)
+- Unused enhancers: **automatically excluded** by tree-shaking
+
+**When to use subpath imports:**
+
+- Older bundlers (webpack <5) with poor tree-shaking
+- Explicit control over what gets included
+- Personal/team preference for clarity
+
+This repo's ESLint rule is **disabled by default** since testing confirms effective tree-shaking with barrel imports.
+
 ### Callable leaf signals (DX sugar only)
 
 SignalTree provides TypeScript support for callable syntax on leaf signals as developer experience sugar:

package/dist/constants.js

@@ -0,0 +1,6 @@
+const SHARED_DEFAULTS = Object.freeze({
+  PATH_CACHE_SIZE: 1000
+});
+const DEFAULT_PATH_CACHE_SIZE = SHARED_DEFAULTS.PATH_CACHE_SIZE;
+
+export { DEFAULT_PATH_CACHE_SIZE, SHARED_DEFAULTS };

package/dist/deep-clone.js

@@ -0,0 +1,80 @@
+const globalStructuredClone = typeof globalThis === 'object' && globalThis !== null ? globalThis.structuredClone : undefined;
+function deepClone(value) {
+  if (globalStructuredClone) {
+    try {
+      return globalStructuredClone(value);
+    } catch (_a) {}
+  }
+  return cloneValue(value, new WeakMap());
+}
+function cloneValue(value, seen) {
+  if (value === null || typeof value !== 'object') {
+    return value;
+  }
+  if (typeof value === 'function') {
+    return value;
+  }
+  const existing = seen.get(value);
+  if (existing) {
+    return existing;
+  }
+  if (value instanceof Date) {
+    return new Date(value.getTime());
+  }
+  if (value instanceof RegExp) {
+    return new RegExp(value.source, value.flags);
+  }
+  if (value instanceof Map) {
+    const result = new Map();
+    seen.set(value, result);
+    for (const [key, entryValue] of value) {
+      result.set(cloneValue(key, seen), cloneValue(entryValue, seen));
+    }
+    return result;
+  }
+  if (value instanceof Set) {
+    const result = new Set();
+    seen.set(value, result);
+    for (const entry of value) {
+      result.add(cloneValue(entry, seen));
+    }
+    return result;
+  }
+  if (Array.isArray(value)) {
+    const result = new Array(value.length);
+    seen.set(value, result);
+    for (let i = 0; i < value.length; i++) {
+      result[i] = cloneValue(value[i], seen);
+    }
+    return result;
+  }
+  if (ArrayBuffer.isView(value)) {
+    if (value instanceof DataView) {
+      const bufferClone = cloneValue(value.buffer, seen);
+      return new DataView(bufferClone, value.byteOffset, value.byteLength);
+    }
+    const viewWithSlice = value;
+    if (typeof viewWithSlice.slice === 'function') {
+      return viewWithSlice.slice();
+    }
+    const bufferClone = cloneValue(value.buffer, seen);
+    return new value.constructor(bufferClone, value.byteOffset, value.length);
+  }
+  if (value instanceof ArrayBuffer) {
+    return value.slice(0);
+  }
+  const proto = Object.getPrototypeOf(value);
+  const result = proto ? Object.create(proto) : {};
+  seen.set(value, result);
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor) continue;
+    if ('value' in descriptor) {
+      descriptor.value = cloneValue(descriptor.value, seen);
+    }
+    Object.defineProperty(result, key, descriptor);
+  }
+  return result;
+}
+
+export { deepClone };

package/dist/deep-equal.js

@@ -0,0 +1,41 @@
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a == null || b == null) return a === b;
+  const typeA = typeof a;
+  const typeB = typeof b;
+  if (typeA !== typeB) return false;
+  if (typeA !== 'object') return false;
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() === b.getTime();
+  }
+  if (a instanceof RegExp && b instanceof RegExp) {
+    return a.source === b.source && a.flags === b.flags;
+  }
+  if (a instanceof Map && b instanceof Map) {
+    if (a.size !== b.size) return false;
+    for (const [key, value] of a) {
+      if (!b.has(key) || !deepEqual(value, b.get(key))) return false;
+    }
+    return true;
+  }
+  if (a instanceof Set && b instanceof Set) {
+    if (a.size !== b.size) return false;
+    for (const value of a) {
+      if (!b.has(value)) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+  if (Array.isArray(b)) return false;
+  const objA = a;
+  const objB = b;
+  const keysA = Object.keys(objA);
+  const keysB = Object.keys(objB);
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every(key => key in objB && deepEqual(objA[key], objB[key]));
+}
+
+export { deepEqual };

package/dist/enhancers/batching/lib/batching.js

@@ -0,0 +1,161 @@
+import { isNodeAccessor } from '../../../lib/utils.js';
+
+let updateQueue = [];
+let isUpdating = false;
+let flushTimeoutId;
+let currentBatchingConfig = {};
+function addToQueue(update, config = currentBatchingConfig) {
+  const maxSize = config.maxBatchSize ?? 100;
+  if (update.path) {
+    updateQueue = updateQueue.filter(existing => existing.path !== update.path);
+  }
+  updateQueue.push(update);
+  if (updateQueue.length > maxSize) {
+    flushUpdates();
+    return true;
+  }
+  scheduleFlush(config);
+  return false;
+}
+function scheduleFlush(config) {
+  if (flushTimeoutId !== undefined) {
+    clearTimeout(flushTimeoutId);
+  }
+  const delay = config.autoFlushDelay ?? 16;
+  flushTimeoutId = setTimeout(() => {
+    flushUpdates();
+  }, delay);
+}
+function flushUpdates() {
+  if (isUpdating) return;
+  let queue;
+  do {
+    if (updateQueue.length === 0) return;
+    isUpdating = true;
+    queue = updateQueue;
+    updateQueue = [];
+    if (flushTimeoutId !== undefined) {
+      clearTimeout(flushTimeoutId);
+      flushTimeoutId = undefined;
+    }
+    queue.sort((a, b) => (b.depth ?? 0) - (a.depth ?? 0));
+    try {
+      queue.forEach(({
+        fn
+      }) => fn());
+    } finally {
+      isUpdating = false;
+    }
+  } while (updateQueue.length > 0);
+}
+function batchUpdates(fn, path) {
+  const startTime = performance.now();
+  const depth = 0;
+  const update = {
+    fn,
+    startTime,
+    depth,
+    path
+  };
+  const wasFlushed = addToQueue(update, currentBatchingConfig);
+  if (!wasFlushed) {
+    const isTimedOut = currentBatchingConfig.batchTimeoutMs && updateQueue.length > 0 && startTime - updateQueue[0].startTime >= currentBatchingConfig.batchTimeoutMs;
+    if (isTimedOut) {
+      flushUpdates();
+    } else if (!isUpdating && updateQueue.length > 0) {
+      queueMicrotask(() => {
+        flushUpdates();
+      });
+    }
+  }
+}
+function withBatching(config = {}) {
+  const {
+    enabled = true
+  } = config;
+  currentBatchingConfig = {
+    ...currentBatchingConfig,
+    ...config
+  };
+  return tree => {
+    if (!enabled) {
+      return tree;
+    }
+    const originalTreeCall = tree.bind(tree);
+    const enhancedTree = function (...args) {
+      if (args.length === 0) {
+        return originalTreeCall();
+      } else {
+        batchUpdates(() => {
+          if (args.length === 1) {
+            const arg = args[0];
+            if (typeof arg === 'function') {
+              originalTreeCall(arg);
+            } else {
+              originalTreeCall(arg);
+            }
+          }
+        });
+      }
+    };
+    Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
+    Object.assign(enhancedTree, tree);
+    if ('state' in tree) {
+      Object.defineProperty(enhancedTree, 'state', {
+        value: tree.state,
+        enumerable: false,
+        configurable: true
+      });
+    }
+    if ('$' in tree) {
+      Object.defineProperty(enhancedTree, '$', {
+        value: tree['$'],
+        enumerable: false,
+        configurable: true
+      });
+    }
+    enhancedTree.batchUpdate = updater => {
+      batchUpdates(() => {
+        const current = originalTreeCall();
+        const updates = updater(current);
+        Object.entries(updates).forEach(([key, value]) => {
+          const property = enhancedTree.state[key];
+          if (property && 'set' in property) {
+            property.set(value);
+          } else if (isNodeAccessor(property)) {
+            property(value);
+          }
+        });
+      });
+    };
+    return enhancedTree;
+  };
+}
+function withHighPerformanceBatching() {
+  return withBatching({
+    enabled: true,
+    maxBatchSize: 200,
+    batchTimeoutMs: 0
+  });
+}
+function flushBatchedUpdates() {
+  if (updateQueue.length > 0) {
+    const queue = updateQueue.slice();
+    updateQueue = [];
+    isUpdating = false;
+    queue.sort((a, b) => (b.depth ?? 0) - (a.depth ?? 0));
+    queue.forEach(({
+      fn
+    }) => {
+      fn();
+    });
+  }
+}
+function hasPendingUpdates() {
+  return updateQueue.length > 0;
+}
+function getBatchQueueSize() {
+  return updateQueue.length;
+}
+
+export { flushBatchedUpdates, getBatchQueueSize, hasPendingUpdates, withBatching, withHighPerformanceBatching };

package/dist/enhancers/computed/lib/computed.js

@@ -0,0 +1,21 @@
+import { computed } from '@angular/core';
+import { createEnhancer } from '../../index.js';
+
+function computedEnhancer(_config = {}) {
+  return createEnhancer({
+    name: 'computed',
+    provides: ['computed'],
+    requires: []
+  }, tree => {
+    const computedTree = tree;
+    computedTree.computed = function (computeFn) {
+      return computed(() => computeFn(tree.state));
+    };
+    return computedTree;
+  });
+}
+function createComputed(dependencies, computeFn) {
+  return computed(computeFn);
+}
+
+export { computedEnhancer, createComputed };