@jucie.io/state 1.0.1

package/dist/admin/unpack.js

@@ -0,0 +1,88 @@
+import { 
+  MAGIC, VERSION, 
+  decodeObject,
+  calculateChecksum, base64urlDecode,
+  readUint16, readUint8, readUint32
+} 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 ----------
+
+/**
+ * Import a binary capsule string created by exportState.
+ * Returns decoded data object with metadata.
+ * @param {String} capsuleString - Base64url encoded capsule
+ * @param {Function} [cb] - Optional callback(data)
+ */
+export async function unpack(capsuleString, cb) {
+  // 1) Decode
+  const capsule = base64urlDecode(capsuleString);
+
+  // 2) Sanity checks
+  if (capsule.length < 15) {
+    throw new Error("Invalid capsule: too short");
+  }
+
+  // Magic
+  for (let i = 0; i < 4; i++) {
+    if (capsule[i] !== MAGIC[i]) throw new Error("Invalid capsule: bad magic");
+  }
+
+  // Version
+  const version = readUint16(capsule, 4);
+  if (version !== VERSION) {
+    throw new Error(`Unsupported capsule version: ${version}`);
+  }
+
+  // Flags (reserved)
+  const flags = readUint8(capsule, 6);
+
+  // Checksum
+  const storedChecksum = readUint32(capsule, 7);
+
+  // Payload length
+  const payloadLength = readUint32(capsule, 11);
+  if (payloadLength < 0) throw new Error("Invalid capsule: negative payload length");
+  if (capsule.length !== 15 + payloadLength) throw new Error("Invalid capsule: length mismatch");
+
+  const payload = capsule.slice(15);
+
+  // 3) Verify checksum
+  const actualChecksum = calculateChecksum(payload);
+  if (storedChecksum !== actualChecksum) {
+    throw new Error("Integrity check failed: checksum mismatch");
+  }
+
+  // 4) Decode payload
+  let offset = 0;
+  
+  // Decode data
+  const dataLength = readUint32(payload, offset);
+  offset += 4;
+  
+  if (offset + dataLength > payload.length) {
+    throw new Error(`Data length ${dataLength} exceeds payload bounds at offset ${offset}`);
+  }
+  
+  const [data] = decodeObject(payload.slice(offset, offset + dataLength));
+
+  // 5) Call callback if provided
+  if (cb) cb(data);
+
+  return {
+    data,   // Add 'data' key for generic usage
+    meta: {
+      version,
+      flags,
+      bytes: capsule.length,
+      checksum: actualChecksum.toString(16),
+    },
+  };
+}

package/dist/lib/TOKENS.js

@@ -0,0 +1,18 @@
+export const GLOBAL_TAG = '*';
+export const STATE_CONTEXT = Symbol('STATE_CONTEXT');
+export const MATCHER = Symbol('MATCHER');
+export const CREATED = 'CREATED';
+export const DELETED = 'DELETED';
+export const UPDATED = 'UPDATED';
+
+// Marker type bitflags
+export const MARKER_GLOBAL = 1;  // 0b001
+export const MARKER_SINGLE = 2;  // 0b010
+export const MARKER_MANY = 4;    // 0b100
+export const MARKER_EPHEMERAL = 8; // 0b1000
+
+// Comparison result constants
+export const MATCH_EXACT = 0;      // Markers are identical
+export const MATCH_PARENT = 1;      // controlMarker is child of comparedMarker (parent changed)
+export const MATCH_CHILD = 2;       // comparedMarker is child of controlMarker (child changed)
+export const MATCH_NONE = -1;       // No relationship

package/dist/lib/change.js

@@ -0,0 +1,94 @@
+import { GLOBAL_TAG, CREATED, DELETED, UPDATED } from './TOKENS.js';
+import { dispatch } from './marker.js';
+
+export const OPERATION_INVERSES = {
+  [CREATED]: DELETED,
+  [DELETED]: CREATED,
+  [UPDATED]: UPDATED,
+}
+
+/**
+ * Determines the operation type based on from/to values
+ * 
+ * @private
+ * @param {*} from - Previous value
+ * @param {*} to - New value
+ * @returns {'created'|'deleted'|'updated'} Operation type
+ */
+function determineOperation(to, from) {
+  if (from === undefined) return CREATED;
+  if (to === undefined) return DELETED;
+  return UPDATED;
+}
+
+/**
+ * Creates a change object with the given parameters
+ * 
+ * @param {string} method - Method that triggered the change
+ * @param {*} from - Previous value
+ * @param {*} to - New value
+ * @returns {Object} Change object
+ * @example
+ * createChange('set', undefined, 'new value') 
+ * // => { method: 'set', operation: 'created', from: undefined, to: 'new value' }
+ */
+export function createChange(marker, method, to, from) {
+  return dispatch(marker, {
+    global: () => ({
+      path: GLOBAL_TAG,
+      method,
+      operation: determineOperation(to, from),
+      from,
+      to
+    }),
+    path: (marker) => ({
+      path: marker.path,
+      method,
+      operation: determineOperation(to, from),
+      from,
+      to
+    }),
+  });
+}
+
+/**
+ * Inverts a change object for undo operations
+ * 
+ * @param {Object} change - Change object to invert
+ * @param {string} change.method - Original method
+ * @param {string} change.operation - Original operation
+ * @param {*} change.from - Original from value
+ * @param {*} change.to - Original to value
+ * @returns {Object} Inverted change object
+ * @example
+ * invertChange({ method: 'set', operation: 'created', from: undefined, to: 'value' })
+ * // => { method: 'set', operation: 'deleted', from: 'value', to: undefined }
+ */
+export function invertChange(change) {
+  const {address, path, method, from, to, operation } = change;
+  return {
+    address,
+    path,
+    method,
+    to: from,
+    from: to,
+    operation: invertOperation(operation),
+  }
+}
+
+export function invertOperation(operation) {
+  return OPERATION_INVERSES[operation];
+}
+
+/**
+ * Checks if a change needs to be inverted based on the method
+ * 
+ * @param {string} method - Method to check
+ * @returns {boolean} True if the change should be inverted
+ * @example
+ * shouldInvertChange('undo') // => true
+ * shouldInvertChange('set') // => false
+ */
+export function shouldInvertChange(method) {
+  return ['undo', 'redo', 'stepBackward', 'stepForward'].includes(method);
+}

package/dist/lib/global.js

@@ -0,0 +1,42 @@
+import { STATE_CONTEXT } from './TOKENS.js';
+
+/**
+ * Registers the state globally, but only if no state has already been set.
+ * @param {object} state 
+ */
+
+export function provideState(state) {
+  if (!globalThis[STATE_CONTEXT]) {
+    globalThis[STATE_CONTEXT] = state;
+  }
+}
+
+export function hasState() {
+  return globalThis[STATE_CONTEXT] !== undefined;
+}
+
+/**
+ * Forcefully override the state in the global context.
+ * Useful for testing or resetting.
+ */
+export function forceState(state) {
+  globalThis[STATE_CONTEXT] = state;
+}
+
+/**
+ * Retrieves the globally registered state.
+ */
+export function getState() {
+  return globalThis[STATE_CONTEXT] || null;
+}
+
+/**
+ * Retrieves the globally registered state.
+ */
+export function useState() {
+  return getState();
+}
+
+export function clearState() {
+  globalThis[STATE_CONTEXT] = undefined;
+}

package/dist/lib/gsru.js

@@ -0,0 +1,125 @@
+import { isGlobalPath, dispatch } from './marker.js';
+import { traverse } from './tree/traverse.js';
+import { graft, detach, replace } from './tree/mutate.js';
+import { isPrimitive } from '../utils/isPrimitive.js';
+import { clone } from '../utils/clone.js';
+
+function spread(value) {
+  if (Array.isArray(value)) {
+    return [...value];
+  }
+  if (typeof value === 'object' && value !== null) {
+    return {...value};
+  }
+  return value;
+}
+
+export function get(state, marker, cb) {
+  let shouldCallCallback = false;
+  try {
+    return dispatch(marker, {
+      global: () => {
+        shouldCallCallback = true;
+        return state;
+      },
+      path: ({path}) => {
+        shouldCallCallback = true;
+        return traverse(state, path);
+      }
+    });
+  } catch (error) {
+    console.error(error);
+    return undefined;
+  } finally {
+    if (shouldCallCallback && cb) {
+      cb(marker);
+    }
+  }
+}
+
+export function set(state, marker, value, method, cb) {
+  let from;
+  let shouldCallCallback = false;
+  
+  try {
+  return dispatch(marker, {
+      global: () => {
+        from = {...state};
+        state = replace(state, value);
+        shouldCallCallback = true;
+        return value;
+      },
+      path: ({path}) => {
+        from = spread(traverse(state, path));
+        graft(state, path, value);
+        shouldCallCallback = true;
+        return value;
+      }
+    });
+  } catch (error) {
+    console.error(error);
+    return undefined;
+  } finally {
+    if (shouldCallCallback && cb) {
+      cb(marker, method, value, from);
+    }
+  }
+}
+
+export function remove(state, marker, method, cb) {
+  let from;
+  let shouldCallCallback = false;
+  try {
+  return dispatch(marker, {
+      global: () => {
+        from = state;
+        state = replace(state, {});
+        shouldCallCallback = true;
+        return from;
+      },
+      path: ({path}) => { 
+        from = detach(state, path);
+        shouldCallCallback = true;
+        return from;
+      }
+    });
+  } catch (error) {
+    console.error(error);
+    return undefined;
+  } finally {
+    if (cb) {
+      cb(marker, method, undefined, from);
+    }
+  }
+}
+
+export function update(state, marker, fn, method, cb) {
+  let from, to;
+  let shouldCallCallback = false;
+  try {
+  return dispatch(marker, {
+      global: () => {
+        from = state;
+        to = fn(state);
+        state = replace(state, to);
+        shouldCallCallback = true;
+        return to;
+      },
+      path: ({ path }) => {
+        from = isGlobalPath(path) ? state : traverse(state, path);
+        const clonePrev = isPrimitive(from) ? from : clone(from);
+        to = fn(clonePrev);
+        graft(state, path, to);
+        shouldCallCallback = true;
+        return to;
+      }
+    });
+  } catch (error) {
+    console.error(error);
+    return undefined;
+  } finally {
+    if (shouldCallCallback && cb) {
+      cb(marker, method, to, from);
+    }
+  }
+}

package/dist/lib/marker.js

@@ -0,0 +1,233 @@
+import { encodePath } from './pathEncoder.js';
+import { GLOBAL_TAG } from './TOKENS.js';
+import {
+  MARKER_GLOBAL,
+  MARKER_SINGLE,
+  MARKER_MANY,
+  MARKER_EPHEMERAL,
+  MATCH_EXACT,
+  MATCH_PARENT,
+  MATCH_CHILD,
+  MATCH_NONE 
+} from './TOKENS.js';
+
+// Marker type bitflags
+
+// Helper functions to check marker type
+export function isGlobalMarker(marker) {
+  return (marker.type & MARKER_GLOBAL) === MARKER_GLOBAL;
+}
+
+export function isPathMarker(marker) {
+  return (marker.type & MARKER_SINGLE) === MARKER_SINGLE;
+}
+
+export function isMarkers(marker) {
+  return (marker.type & MARKER_MANY) === MARKER_MANY;
+}
+
+export function isEphemeralMarker(marker) {
+  return (marker.type & MARKER_EPHEMERAL) === MARKER_EPHEMERAL;
+}
+
+export function isGlobalPath(path) {
+  return !path || path.length === 0 || path === GLOBAL_TAG || path[0] === GLOBAL_TAG;
+}
+
+export function normalizePaths(args = []) {  
+  const len = args.length;
+  if (len === 0) return [0, [] ];
+  if (len === 1 && args[0] === GLOBAL_TAG) return [0, [] ];
+  
+  if (Array.isArray(args[0])) {
+    return len === 1 
+      ? [1, [args[0]] ]
+      : [len, args ];
+  }
+  
+  return [1, [[...args]] ];
+}
+
+function pathHasEphemeral(path) {
+  if (!Array.isArray(path)) {
+    return false;
+  }
+
+  for (let i = 0; i < path.length; i++) {
+    const segment = path[i];
+    if (typeof segment === 'string' && segment.charCodeAt(0) === 46) { // '.'
+      return true;
+    }
+  }
+
+  return false;
+}
+
+// Marker factory
+export function createMarker(paths = []) {
+  if (isGlobalPath(paths)) {
+    return {
+      address: GLOBAL_TAG,
+      isMarker: true,
+      length: 0,
+      path: [],
+      children: null,
+      type: MARKER_GLOBAL
+    };
+  }
+  
+  const [length, normalizedPaths] = normalizePaths(paths);
+  const type = length === 1 ? MARKER_SINGLE : MARKER_MANY;
+  const path = length === 1 ? normalizedPaths[0] : normalizedPaths;
+  const children = length > 1 ? normalizedPaths.map(path => createMarker(path)) : null;
+  const isEphemeral = type === MARKER_SINGLE
+    ? pathHasEphemeral(path)
+    : children.some(child => isEphemeralMarker(child));
+
+  let markerType = type;
+  if (isEphemeral) {
+    markerType |= MARKER_EPHEMERAL;
+  }
+
+  return {
+    address: type === MARKER_SINGLE ? encodePath(path) : null,
+    isMarker: true,
+    length,
+    path,
+    children,
+    type: markerType
+  };
+}
+
+export function createChildMarker(parentMarker, childPaths) {
+  if (childPaths.length === 0) {
+    return parentMarker;
+  }
+  // Normalize the child paths
+  const [childLength, normalizedChildPaths] = normalizePaths(childPaths);
+  
+  // Handle global marker - just return marker with child paths
+  if (isGlobalMarker(parentMarker)) {
+    return createMarker(normalizedChildPaths, parentMarker.state);
+  }
+  
+  // Handle single path marker
+  if (isPathMarker(parentMarker)) {
+    if (childLength === 0) {
+      // No child paths, return parent as-is
+      return parentMarker;
+    }
+    
+    if (childLength === 1) {
+      // Single child path - append to parent path
+      const newPath = [...parentMarker.path, ...normalizedChildPaths[0]];
+      return createMarker(newPath, parentMarker.state);
+    } else {
+      // Multiple child paths - create many markers
+      const newPaths = normalizedChildPaths.map(childPath => 
+        [...parentMarker.path, ...childPath]
+      );
+      return createMarker(newPaths, parentMarker.state);
+    }
+  }
+  
+  // Handle many markers - recursively create child markers for each
+  if (isMarkers(parentMarker)) {
+    const newMarkers = new Array(parentMarker.length);
+    let i = 0;
+    while (i < parentMarker.length) {
+      newMarkers[i] = createChildMarker(parentMarker.children[i], childPaths);
+      i++;
+    }
+    
+    // Collect all paths from the new markers
+    const allPaths = [];
+    i = 0;
+    while (i < newMarkers.length) {
+      const marker = newMarkers[i];
+      if (isPathMarker(marker)) {
+        allPaths.push(marker.path);
+      } else if (isMarkers(marker)) {
+        let j = 0;
+        while (j < marker.length) {
+          allPaths.push(marker.children[j].path);
+          j++;
+        }
+      }
+      i++;
+    }
+    
+    return createMarker(allPaths, parentMarker.state);
+  }
+  
+  // Fallback - shouldn't reach here
+  return parentMarker;
+}
+
+export function dispatch(marker, { global, path, ephemeral, error }) {
+  try {
+    if (!marker.isMarker) return undefined;
+    if (isGlobalMarker(marker)) return global ? global(marker) : undefined;
+    if (isEphemeralMarker(marker)) return ephemeral ? ephemeral(marker) : path ? path(marker) : undefined;
+    if (isPathMarker(marker)) return path ? path(marker) : undefined;
+    if (isMarkers(marker)) {
+      const results = new Array(marker.length);
+      let i = 0;
+      while (i < marker.length) {
+        const nestedMarker = marker.children[i];
+        results[i] = dispatch(nestedMarker, { global, path, ephemeral, error });
+        i++;
+      }
+      return results;
+    }
+    
+    return undefined;
+  } catch (err) {
+    return error ? error(err.message) : undefined;
+  }
+}
+
+export function compareMarkers(controlMarker, comparedMarker) {
+  // Both are global markers or exact address match
+  if (isGlobalMarker(controlMarker) && isGlobalMarker(comparedMarker)) {
+    return MATCH_EXACT;
+  }
+
+  // If comparedMarker is global, it's always a parent
+  if (isGlobalMarker(comparedMarker)) {
+    return MATCH_PARENT;
+  }
+  
+  // Need addresses to compare
+  if (!controlMarker.address || !comparedMarker.address) {
+    return MATCH_NONE;
+  }
+  
+  // Exact match
+  if (controlMarker.address === comparedMarker.address) {
+    return MATCH_EXACT;
+  }
+  
+  // controlMarker is more nested (child) - parent changed
+  if (controlMarker.address.startsWith(comparedMarker.address + '.')) {
+    return MATCH_PARENT;
+  }
+  
+  // comparedMarker is more nested (child) - child changed
+  if (comparedMarker.address.startsWith(controlMarker.address + '.')) {
+    return MATCH_CHILD;
+  }
+  
+  return MATCH_NONE;
+}
+
+export const Marker = {
+  compare: compareMarkers,
+  create: createMarker,
+  createChild: createChildMarker,
+  dispatch: dispatch,
+  isGlobal: isGlobalMarker,
+  isSingle: isPathMarker,
+  isMarkers: isMarkers,
+  isEphemeral: isEphemeralMarker
+};

package/dist/lib/pathEncoder.js

@@ -0,0 +1,89 @@
+import { GLOBAL_TAG } from './TOKENS.js';
+
+// Fast helpers
+function escapeStr(str) {
+  // Order matters: escape ~ first, then .
+  let out = "";
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (ch === "~") out += "~~";
+    else if (ch === ".") out += "~d";
+    else out += ch;
+  }
+  // Represent empty strings as ~e to avoid trailing-dot filenames
+  return out.length === 0 ? "~e" : out;
+}
+
+function unescapeStr(str) {
+  let out = "";
+  for (let i = 0; i < str.length; i++) {
+    const ch = str[i];
+    if (ch === "~") {
+      const next = str[++i];
+      if (next === "~") out += "~";
+      else if (next === "d") out += ".";
+      else if (next === "e") out += ""; // empty string marker
+      else {
+        // Unknown escape: treat as literal (robustness)
+        out += "~" + (next ?? "");
+      }
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+export function encodePath(segments) {
+  // segments: array of strings or integers
+  // Produces: filename/URL-safe string like "sfoo.n0.sbaz"
+  const parts = new Array(segments.length);
+  for (let i = 0; i < segments.length; i++) {
+    const v = segments[i];
+    if (typeof v === "number" && Number.isInteger(v)) {
+      // 'n' tag
+      parts[i] = "n" + String(v); // decimal; includes "-" if negative
+    } else if (typeof v === "string") {
+      // 's' tag
+      parts[i] = "s" + escapeStr(v);
+    } else {
+      // If you need more types, add here (e.g., booleans 'b', floats 'f').
+      throw new TypeError(`Unsupported segment type at index ${i}: ${v}`);
+    }
+  }
+  // Use '.' as separator (safe in URLs and filenames; we avoid trailing '.')
+  return parts.join(".");
+}
+
+export function decodeAddress(address) {
+  if (address === GLOBAL_TAG) return GLOBAL_TAG;
+  if (address.length === 0) return [];
+  const raw = address.split(".");
+  const out = new Array(raw.length);
+  for (let i = 0; i < raw.length; i++) {
+    const token = raw[i];
+    if (token.length === 0) {
+      // Disallow empty tokens (would imply trailing or double dots)
+      throw new Error("Invalid address: empty token");
+    }
+    const tag = token[0];
+    const body = token.slice(1);
+    if (tag === "n") {
+      // Fast parse (no regex)
+      if (body.length === 0 || !/^[-]?\d+$/.test(body)) {
+        throw new Error(`Invalid numeric token: "${token}"`);
+      }
+      const num = Number(body);
+      // Ensure it was an integer
+      if (!Number.isInteger(num)) {
+        throw new Error(`Non-integer numeric token: "${token}"`);
+      }
+      out[i] = num;
+    } else if (tag === "s") {
+      out[i] = unescapeStr(body);
+    } else {
+      throw new Error(`Unknown type tag "${tag}" in token "${token}"`);
+    }
+  }
+  return out;
+}