@jucie.io/state 1.0.1

package/dist/Plugin.js

@@ -0,0 +1,36 @@
+export class Plugin {
+
+  static name = null;
+  static options = {};
+
+  static configure(options) {
+    options = {...this.options, ...options};
+    return {
+      install: (state) => this.install(state, options),
+      name: this.name,
+      options
+    }
+  }
+
+  static install(state, options) {
+    options = {...this.options, ...options};
+    const pluginInstance = new this(state, options);
+
+    Object.defineProperty(pluginInstance, 'state', {
+      value: state,
+      writable: false,
+      configurable: false
+    });
+    
+    Object.defineProperty(pluginInstance, 'options', {
+      value: options,
+      writable: false,
+      configurable: false
+    });
+
+    
+    return pluginInstance;
+  }
+}
+
+export default Plugin;

package/dist/State.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @jucie-state/state - State management module
+ */
+
+export interface StateValue {
+  get(path: string[]): any;
+  set(path: string[], value: any): void;
+  update(path: string[], fn: (value: any) => any): void;
+  delete(path: string[]): void;
+  keys(path?: string[]): string[];
+  has(path: string[]): boolean;
+  subscribe(path: string[], callback: (value: any) => void): () => void;
+  unsubscribe(path: string[], callback: (value: any) => void): void;
+}
+
+export interface StateExport {
+  exportState(path?: string[]): any;
+  importState(data: any, path?: string[]): void;
+  clearState(path?: string[]): void;
+}
+export declare class State {
+  static create(config?: any): State;
+  static createStateExport(config?: any): StateExport;
+  
+  get(path: string[]): any;
+  set(path: string[], value: any): void;
+  update(path: string[], fn: (value: any) => any): void;
+  delete(path: string[]): void;
+  keys(path?: string[]): string[];
+  has(path: string[]): boolean;
+  subscribe(path: string[], callback: (value: any) => void): () => void;
+  unsubscribe(path: string[], callback: (value: any) => void): void;
+}
+
+
+// Global state utilities
+export declare function provideState(state: State): void;
+export declare function hasState(): boolean;
+
+export declare function createState(config?: any): State;
+export declare function createStateExport(config?: any): StateExport;
+export declare function useState(path: string[]): any;
+export declare function forceState(path: string[], value: any): void;
+export declare function clearState(path: string[]): void;

package/dist/State.js

@@ -0,0 +1,243 @@
+import { get, set, remove, update } from './lib/gsru.js';
+import { createMarker, createChildMarker, dispatch } from './lib/marker.js';
+import { pack } from './admin/pack.js';
+import { unpack } from './admin/unpack.js';
+import { clear } from './lib/tree/mutate.js';
+import { findFirstNode, findAllNodes } from './lib/tree/seek.js';
+import { CREATED, DELETED, UPDATED } from './lib/TOKENS.js';
+import { createChange } from './lib/change.js';
+
+export class State {
+  #state;
+  #marker;
+  #batchDepth = 0;
+  #changeHandler;
+  #accessHandler;
+  #plugins = new Map();
+
+  static create (state = {}) {
+    const instance = new State(state);
+
+    return instance;
+  }
+
+  constructor(state, marker = null, changeHandler = null, accessHandler = null) {
+    this.#state = state;
+    this.#changeHandler = changeHandler || this.#createChangeHandler();
+    this.#accessHandler = accessHandler || this.#createAccessHandler();
+    this.#marker = marker || createMarker();
+    this.#batchDepth = 0;
+  }
+
+  install(...plugins) {
+    const initializeFunctions = new Map();
+
+    for (const plugin of plugins) {
+      if (this.#plugins.has(plugin.name)) {
+        console.warn(`Plugin "${plugin.name}" already installed`);
+        continue;
+      }
+
+      if (!plugin.install) {
+        console.warn(`Plugin "${plugin.name}" does not have an install function`);
+        continue;
+      }
+
+      const pluginInstance = plugin.install(this);
+      this.#plugins.set(plugin.name, pluginInstance);
+
+      if (pluginInstance.initialize) {
+        initializeFunctions.set(plugin.name, () => pluginInstance.initialize(this, pluginInstance.options));
+      }
+
+      if (pluginInstance.actions) {
+        const actions = pluginInstance.actions(this, pluginInstance.options);
+        Object.defineProperty(this, plugin.name, {
+          value: actions,
+          writable: false,
+          enumerable: true,
+          configurable: false
+        });
+      }
+    }
+
+    initializeFunctions.forEach(initialize => initialize());
+    return this;
+  }
+
+  get batching() {
+    return this.#batchDepth > 0;
+  }
+
+  // Core State Accessors
+  get(...args) {
+    return get(this.#state, createChildMarker(this.#marker, args), this.#accessHandler);
+  }
+
+  has(...args) {
+    const marker = createChildMarker(this.#marker, args);
+    return dispatch(marker, {
+      global: () => undefined,
+      path: (marker) => get(this.#state, marker, this.#accessHandler) !== undefined,
+    });
+  }
+
+  keys(...args) {
+    const marker = createChildMarker(this.#marker, args);
+    return dispatch(marker, {
+      global: () => Object.keys(this.#state),
+      path: (marker) => Object.keys(get(this.#state, marker, this.#accessHandler) || {}),
+    });
+  }
+
+  typeof(...args) {
+    const marker = createChildMarker(this.#marker, args);
+    const value = dispatch(marker, {
+      global: () => undefined,
+      path: ({ path }) => typeof get(this.#state, path, this.#accessHandler),
+    });
+    return value;
+  }
+
+  // Queries
+  findWhere(key, matcher = 'is', value) {
+    const state = get(this.#state, this.#marker, this.#accessHandler);
+    return findFirstNode(state, key, matcher, value);
+  }
+
+  findAllWhere(key, matcher = 'is', value) {
+    const state = get(this.#state, this.#marker, this.#accessHandler);
+    return findAllNodes(state, key, matcher, value);
+  }
+
+  // Mutations
+  set(...args) {
+    const value = args.pop();    
+    const marker = createChildMarker(this.#marker, args);
+    // No sync tombstone check - let async processing handle conflicts
+    return set(this.#state, marker, value, 'set', this.#changeHandler);
+  }
+
+  update(...args) {
+    const fn = args.pop();
+    const marker = createChildMarker(this.#marker, args);
+    
+    // No sync tombstone check - let async processing handle conflicts  
+    return update(this.#state, marker, fn, 'update', this.#changeHandler);
+  }
+
+  apply(changeEntries) {
+    for (const changeEntry of changeEntries) {
+      const { path, operation, to } = changeEntry;
+
+      const marker = createChildMarker(this.#marker, path);
+      switch (operation) {
+        case CREATED:
+        case UPDATED:
+          set(this.#state, marker, to, 'apply', this.#changeHandler);
+          break;
+        case DELETED:
+          remove(this.#state, marker, 'apply', this.#changeHandler);
+          break;
+      }
+    }
+  }
+
+  load(value) {
+    set(this.#state, this.#marker, value, 'load', this.#changeHandler);
+    return this;
+  }
+
+  remove(...args) {
+    const marker = createChildMarker(this.#marker, args);
+    return remove(this.#state, marker, 'remove', this.#changeHandler);
+  }
+
+  // Lifecycle / Admin
+  async export(...args) {
+    try {
+      const marker = createChildMarker(this.#marker, args);
+      const promises = dispatch(marker, {
+        global: async () => await pack(this.#state),
+        path: async (path) => await pack(get(this.#state, path, this.#accessHandler)),
+      });
+      if (!Array.isArray(promises)) {
+        return await promises;
+      }
+      return await Promise.all(promises);
+    } catch (err) {
+      console.trace(`Failed to export state: ${err.message}`);
+      throw err
+    }
+  }
+
+  async import(exportedData) {
+    try {
+      const { data } = await unpack(exportedData);
+      this.load(data);
+      return this;
+    } catch (err) {
+      console.trace(`Failed to import state: ${err.message}`);
+      throw err
+    }
+  }
+
+  reset() {
+    clear(this.#state);
+    for (const plugin of this.#plugins.values()) {
+      if (plugin.reset) {
+        plugin.reset();
+      }
+    }
+    this.#changeHandler = this.#createChangeHandler();
+    this.#marker = createMarker([], this);
+    this.#batchDepth = 0;
+  }
+
+
+  // Reactivity Utilities
+  ref(...path) {
+    const marker = createChildMarker(this.#marker, path);
+    return new State(this.#state, marker, this.#changeHandler, this.#accessHandler);
+  }
+
+  batch(fn) {
+    this.#batchDepth++;
+    this.#notifyPlugins('onBatchStart', this.batching);
+    if (fn) {
+      fn(this);
+      return this.endBatch();
+    }
+    return () => this.endBatch();
+  }
+
+  endBatch() {
+    this.#batchDepth--;
+    if (this.#batchDepth === 0) {
+      this.#notifyPlugins('onBatchEnd');
+    }
+    return this;
+  }
+
+  // Private change handler
+  #createChangeHandler() {
+    return (marker, method, to = undefined, from = undefined) => {
+      this.#notifyPlugins('onStateChange', marker, createChange(marker, method, to, from), this.batching);
+    }
+  }
+
+  #createAccessHandler() {
+    return (marker) => this.#notifyPlugins('onStateAccess', marker);
+  }
+
+  #notifyPlugins(event, ...args) {
+    for (const plugin of this.#plugins.values()) {
+      if (typeof plugin[event] === 'function') {
+        plugin[event](...args);
+      }
+    }
+  }
+}
+
+export const createState = (...args) => State.create(...args);
+export const isState = (target) => target instanceof State;

package/dist/admin/binary.js

@@ -0,0 +1,90 @@
+import { encode, decode } from 'cbor-x';
+
+// Magic header for binary capsules
+export const MAGIC = new Uint8Array([0x4A, 0x53, 0x43, 0x32]); // "JSC2" (Object Capsule v2)
+export const VERSION = 2;
+
+// Base64url encoding/decoding utilities
+export function base64urlEncode(buffer) {
+  // Process in chunks to avoid call stack overflow for large buffers
+  const chunkSize = 8192; // Process 8KB at a time
+  let binaryString = '';
+  
+  for (let i = 0; i < buffer.length; i += chunkSize) {
+    const chunk = buffer.slice(i, i + chunkSize);
+    binaryString += String.fromCharCode(...chunk);
+  }
+  
+  return btoa(binaryString)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=/g, '');
+}
+
+export function base64urlDecode(str) {
+  const base64 = str
+    .replace(/-/g, '+')
+    .replace(/_/g, '/');
+  
+  // Add padding if needed
+  const padded = base64 + '='.repeat((4 - base64.length % 4) % 4);
+  const binaryString = atob(padded);
+  
+  // Convert to Uint8Array efficiently for large strings
+  const result = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    result[i] = binaryString.charCodeAt(i);
+  }
+  return result;
+}
+
+// Simple checksum calculation
+export function calculateChecksum(buffer) {
+  let checksum = 0;
+  for (let i = 0; i < buffer.length; i++) {
+    checksum = ((checksum << 5) - checksum + buffer[i]) >>> 0; // Ensure positive 32-bit
+  }
+  return checksum;
+}
+
+// Binary encoding utilities for capsule header
+export function writeUint32(value, buffer, offset = 0) {
+  const view = new DataView(buffer.buffer, buffer.byteOffset + offset, 4);
+  view.setUint32(0, value, true); // little-endian
+  return offset + 4;
+}
+
+export function readUint32(buffer, offset = 0) {
+  const view = new DataView(buffer.buffer, buffer.byteOffset + offset, 4);
+  return view.getUint32(0, true); // little-endian
+}
+
+export function writeUint16(value, buffer, offset = 0) {
+  const view = new DataView(buffer.buffer, buffer.byteOffset + offset, 2);
+  view.setUint16(0, value, true); // little-endian
+  return offset + 2;
+}
+
+export function readUint16(buffer, offset = 0) {
+  const view = new DataView(buffer.buffer, buffer.byteOffset + offset, 2);
+  return view.getUint16(0, true); // little-endian
+}
+
+export function writeUint8(value, buffer, offset = 0) {
+  buffer[offset] = value;
+  return offset + 1;
+}
+
+export function readUint8(buffer, offset = 0) {
+  return buffer[offset];
+}
+
+// Object encoding using cbor-x
+export function encodeObject(obj) {
+  return encode(obj);
+}
+
+export function decodeObject(buffer) {
+  const obj = decode(buffer);
+  return [obj, buffer.length];
+}

package/dist/admin/buffer.js

@@ -0,0 +1,174 @@
+export function isBrowser() {
+  return typeof window !== "undefined" && typeof window.crypto !== "undefined" && !!window.crypto.subtle;
+}
+
+export function getSubtle() {
+  if (typeof crypto !== "undefined" && crypto.subtle) return crypto.subtle;
+  // Node.js
+  const { webcrypto } = require("node:crypto");
+  return webcrypto.subtle;
+}
+
+// base64url encode/decode for both envs
+export function base64urlEncode(bytes) {
+  if (typeof Buffer !== "undefined" && Buffer.from) {
+    // Node
+    return Buffer.from(bytes).toString("base64")
+      .replace(/=/g, "")
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_");
+  } else {
+    // Browser
+    // Convert bytes -> binary string -> base64 -> base64url
+    let bin = "";
+    for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+    const b64 = btoa(bin);
+    return b64.replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+  }
+}
+
+export function base64urlDecode(str) {
+  // restore padding
+  const pad = str.length % 4 === 2 ? "=="
+            : str.length % 4 === 3 ? "="
+            : str.length % 4 === 0 ? ""
+            : "=".repeat(4 - (str.length % 4));
+  const b64 = str.replace(/-/g, "+").replace(/_/g, "/") + pad;
+
+  if (typeof Buffer !== "undefined" && Buffer.from) {
+    const buf = Buffer.from(b64, "base64");
+    return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  } else {
+    // Browser
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+    return out;
+  }
+}
+
+// Canonical JSON (stable ordering) to avoid hash drift due to key order
+export function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map(v => stableStringify(v)).join(",");
+    return `[${items}]`;
+  }
+  const keys = Object.keys(value).sort();
+  const props = keys.map(k => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",");
+  return `{${props}}`;
+}
+
+// Optional replacer to omit ephemeral keys
+export function defaultReplacer(key, value) {
+  // drop keys starting with '.' or exactly 'ephemeral'
+  if (key && key[0] === ".") return undefined;
+  return value;
+}
+
+export function applyReplacerDeep(input, replacer = defaultReplacer, parentKey = "") {
+  if (input === null || typeof input !== "object") return input;
+
+  if (Array.isArray(input)) {
+    return input.map(v => applyReplacerDeep(v, replacer));
+  }
+
+  const out = {};
+  for (const k of Object.keys(input)) {
+    const v = replacer(k, input[k]);
+    if (typeof v !== "undefined") {
+      out[k] = applyReplacerDeep(v, replacer, k);
+    }
+  }
+  return out;
+}
+
+// Convert path IDs with null chars to arrays for JSON serialization
+export function pathIdsToArrays(input) {
+  if (input === null || typeof input !== "object") return input;
+
+  if (Array.isArray(input)) {
+    return input.map(v => {
+      // Check if array element is a string with null character (path ID)
+      if (typeof v === 'string' && v.includes('\0')) {
+        const pathArray = v.split('\0').map(segment => {
+          const [type, value] = segment.split(':');
+          return type === 'n' ? parseInt(value) : value;
+        });
+        return `__pathArray:${JSON.stringify(pathArray)}`;
+      }
+      return pathIdsToArrays(v);
+    });
+  }
+
+  const out = {};
+  for (const k of Object.keys(input)) {
+    const v = input[k];
+    // Check if key contains null character (path ID)
+    if (typeof k === 'string' && k.includes('\0')) {
+      // Convert path ID to array format
+      const pathArray = k.split('\0').map(segment => {
+        const [type, value] = segment.split(':');
+        return type === 'n' ? parseInt(value) : value;
+      });
+      out[`__pathArray:${JSON.stringify(pathArray)}`] = pathIdsToArrays(v);
+    } else {
+      out[k] = pathIdsToArrays(v);
+    }
+  }
+  return out;
+}
+
+// Convert arrays back to path IDs with null chars after JSON parsing
+export function arraysToPathIds(input) {
+  if (input === null || typeof input !== "object") return input;
+
+  if (Array.isArray(input)) {
+    return input.map(v => {
+      // Check if array element is a path array
+      if (typeof v === 'string' && v.startsWith('__pathArray:')) {
+        const pathArray = JSON.parse(v.substring(12)); // Remove '__pathArray:' prefix
+        // Convert array back to path ID with null chars
+        const pathId = pathArray.map(segment => {
+          const type = typeof segment === 'number' ? 'n' : 's';
+          return `${type}:${segment}`;
+        }).join('\0');
+        return pathId;
+      }
+      return arraysToPathIds(v);
+    });
+  }
+
+  const out = {};
+  for (const k of Object.keys(input)) {
+    const v = input[k];
+    // Check if key is a path array
+    if (typeof k === 'string' && k.startsWith('__pathArray:')) {
+      const pathArray = JSON.parse(k.substring(12)); // Remove '__pathArray:' prefix
+      // Convert array back to path ID with null chars
+      const pathId = pathArray.map(segment => {
+        const type = typeof segment === 'number' ? 'n' : 's';
+        return `${type}:${segment}`;
+      }).join('\0');
+      out[pathId] = arraysToPathIds(v);
+    } else {
+      out[k] = arraysToPathIds(v);
+    }
+  }
+  return out;
+}
+
+export async function sha256(bytes) {
+  const subtle = getSubtle();
+  const digest = await subtle.digest("SHA-256", bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+  return new Uint8Array(digest);
+}
+
+export function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let acc = 0;
+  for (let i = 0; i < a.length; i++) acc |= (a[i] ^ b[i]);
+  return acc === 0;
+}

package/dist/admin/pack.js

@@ -0,0 +1,67 @@
+import { defaultReplacer, applyReplacerDeep } from './buffer.js';
+import { 
+  MAGIC, VERSION, 
+  writeUint32, writeUint16, writeUint8,
+  encodeObject,
+  calculateChecksum, base64urlEncode
+} from './binary.js';
+
+// ---------- Binary Capsule Format ----------
+// [ 0..3 ]  Magic "JSC2" (Jucie State Capsule v2)
+// [ 4..5 ]  u16 version (big-endian) = 2
+// [ 6 ]     u8 flags (reserved for future use)
+// [ 7..10 ] u32 checksum (simple checksum)
+// [11..14 ] u32 payloadLength (big-endian)
+// [15.. ]   payload bytes (binary encoded data)
+
+// ---------- Public API ----------
+
+/**
+ * Export any data object as a resilient binary capsule string (base64url).
+ * Reciprocal with importState.
+ * @param {Object} data - The data object to export
+ * @param {Object} options - Export options
+ */
+export async function pack(data, { replacer = defaultReplacer } = {}) {
+  // 1) Clean ephemeral/transient fields
+  const clean = applyReplacerDeep(data, replacer);
+
+  // 2) Encode data to binary
+  const dataBuffer = encodeObject(clean);
+
+  // 3) Create payload: [dataLength:4][data:varies]
+  const payloadLength = 4 + dataBuffer.length;
+  const payload = new Uint8Array(payloadLength);
+  
+  let offset = 0;
+  offset = writeUint32(dataBuffer.length, payload, offset);
+  payload.set(dataBuffer, offset);
+
+  // 4) Calculate checksum
+  const checksum = calculateChecksum(payload);
+
+  // 5) Build capsule
+  const headerLen = 4 + 2 + 1 + 4 + 4; // 15 bytes
+  const capsule = new Uint8Array(headerLen + payload.length);
+
+  // Magic
+  capsule.set(MAGIC, 0);
+
+  // Version u16 LE
+  writeUint16(VERSION, capsule, 4);
+
+  // Flags u8
+  writeUint8(0, capsule, 6);
+
+  // Checksum u32 LE
+  writeUint32(checksum, capsule, 7);
+
+  // Payload length u32 LE
+  writeUint32(payload.length, capsule, 11);
+
+  // Payload
+  capsule.set(payload, 15);
+
+  // 6) Base64url encode (single portable string)
+  return base64urlEncode(capsule);
+}