@shiftbloom-studio/symphony-state 0.0.0

package/dist/react.d.cts

@@ -0,0 +1,40 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { C as Conductor, c as SectionHandle, S as SectionDefinition, D as DerivedSectionDefinition, a as Scheduler } from './types-B1uzdpYH.cjs';
+
+type SymphonyProviderProps = {
+    conductor: Conductor;
+    children: React.ReactNode;
+};
+declare const SymphonyProvider: ({ conductor, children }: SymphonyProviderProps) => react_jsx_runtime.JSX.Element;
+declare const useConductor: () => Conductor;
+
+declare const useSection: <T>(key: string) => SectionHandle<T> & {
+    value: T;
+};
+declare const useSelector: <T, S>(key: string, selector: (value: T) => S, equality?: (a: S, b: S) => boolean) => S;
+
+type SymphonyScriptProps = {
+    state: Record<string, unknown>;
+    globalKey?: string;
+};
+declare const SymphonyScript: ({ state, globalKey }: SymphonyScriptProps) => react_jsx_runtime.JSX.Element;
+
+type AnySectionDefinition = SectionDefinition<unknown> | DerivedSectionDefinition<unknown>;
+type SectionValues<Sections extends Record<string, AnySectionDefinition>> = {
+    [K in keyof Sections]: Sections[K] extends SectionDefinition<infer T> ? T : Sections[K] extends DerivedSectionDefinition<infer T> ? T : never;
+};
+type CreateSymphonyConfig<Sections extends Record<string, AnySectionDefinition>> = {
+    sections: Sections;
+    scheduler?: Scheduler;
+    bootstrap?: Record<string, unknown> | (() => Record<string, unknown> | undefined);
+};
+type SymphonyInstance<Sections extends Record<string, AnySectionDefinition>> = {
+    conductor: Conductor;
+    Provider: typeof SymphonyProvider;
+    useSection: <K extends keyof Sections>(key: K) => ReturnType<typeof useSection<SectionValues<Sections>[K]>>;
+    useSelector: <K extends keyof Sections, S>(key: K, selector: (value: SectionValues<Sections>[K]) => S, equality?: (a: S, b: S) => boolean) => S;
+};
+declare const createSymphony: <Sections extends Record<string, AnySectionDefinition>>(config: CreateSymphonyConfig<Sections>) => SymphonyInstance<Sections>;
+
+export { SymphonyProvider, SymphonyScript, createSymphony, useConductor, useSection, useSelector };

package/dist/react.d.ts

@@ -0,0 +1,40 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import { C as Conductor, c as SectionHandle, S as SectionDefinition, D as DerivedSectionDefinition, a as Scheduler } from './types-B1uzdpYH.js';
+
+type SymphonyProviderProps = {
+    conductor: Conductor;
+    children: React.ReactNode;
+};
+declare const SymphonyProvider: ({ conductor, children }: SymphonyProviderProps) => react_jsx_runtime.JSX.Element;
+declare const useConductor: () => Conductor;
+
+declare const useSection: <T>(key: string) => SectionHandle<T> & {
+    value: T;
+};
+declare const useSelector: <T, S>(key: string, selector: (value: T) => S, equality?: (a: S, b: S) => boolean) => S;
+
+type SymphonyScriptProps = {
+    state: Record<string, unknown>;
+    globalKey?: string;
+};
+declare const SymphonyScript: ({ state, globalKey }: SymphonyScriptProps) => react_jsx_runtime.JSX.Element;
+
+type AnySectionDefinition = SectionDefinition<unknown> | DerivedSectionDefinition<unknown>;
+type SectionValues<Sections extends Record<string, AnySectionDefinition>> = {
+    [K in keyof Sections]: Sections[K] extends SectionDefinition<infer T> ? T : Sections[K] extends DerivedSectionDefinition<infer T> ? T : never;
+};
+type CreateSymphonyConfig<Sections extends Record<string, AnySectionDefinition>> = {
+    sections: Sections;
+    scheduler?: Scheduler;
+    bootstrap?: Record<string, unknown> | (() => Record<string, unknown> | undefined);
+};
+type SymphonyInstance<Sections extends Record<string, AnySectionDefinition>> = {
+    conductor: Conductor;
+    Provider: typeof SymphonyProvider;
+    useSection: <K extends keyof Sections>(key: K) => ReturnType<typeof useSection<SectionValues<Sections>[K]>>;
+    useSelector: <K extends keyof Sections, S>(key: K, selector: (value: SectionValues<Sections>[K]) => S, equality?: (a: S, b: S) => boolean) => S;
+};
+declare const createSymphony: <Sections extends Record<string, AnySectionDefinition>>(config: CreateSymphonyConfig<Sections>) => SymphonyInstance<Sections>;
+
+export { SymphonyProvider, SymphonyScript, createSymphony, useConductor, useSection, useSelector };

package/dist/react.js

@@ -0,0 +1,569 @@
+import { createContext, useContext, useCallback, useSyncExternalStore, useMemo, useRef } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// src/react/SymphonyProvider.tsx
+var SymphonyContext = createContext(null);
+var SymphonyProvider = ({ conductor, children }) => {
+  return /* @__PURE__ */ jsx(SymphonyContext.Provider, { value: conductor, children });
+};
+var useConductor = () => {
+  const conductor = useContext(SymphonyContext);
+  if (!conductor) {
+    throw new Error("SymphonyProvider is missing in the React tree.");
+  }
+  return conductor;
+};
+var useSection = (key) => {
+  const conductor = useConductor();
+  const getSnapshot = useCallback(() => conductor.getSectionValue(key), [
+    conductor,
+    key
+  ]);
+  const subscribe = useCallback(
+    (cb) => conductor.subscribe(key, cb),
+    [conductor, key]
+  );
+  const value = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const handle = useMemo(
+    () => ({
+      value,
+      get: () => value,
+      set: (next) => conductor.getSection(key).set(next),
+      patch: (partial) => conductor.getSection(key).patch(partial),
+      subscribe: (cb) => conductor.subscribe(key, cb)
+    }),
+    [conductor, key, value, subscribe]
+  );
+  return handle;
+};
+var useSelector = (key, selector, equality = Object.is) => {
+  const conductor = useConductor();
+  const selectedRef = useRef();
+  const getSnapshot = useCallback(() => {
+    const value = conductor.getSectionValue(key);
+    const nextSelected = selector(value);
+    if (selectedRef.current !== void 0 && equality(selectedRef.current, nextSelected)) {
+      return selectedRef.current;
+    }
+    selectedRef.current = nextSelected;
+    return nextSelected;
+  }, [conductor, key, selector, equality]);
+  const subscribe = useCallback(
+    (cb) => conductor.subscribe(key, cb),
+    [conductor, key]
+  );
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+var escapeJson = (value) => value.replace(/</g, "\\u003c").replace(/>/g, "\\u003e");
+var SymphonyScript = ({
+  state,
+  globalKey = "__SYMPHONY_STATE__"
+}) => {
+  const serialized = escapeJson(JSON.stringify(state));
+  const script = `window[${JSON.stringify(globalKey)}]=${serialized};`;
+  return /* @__PURE__ */ jsx(
+    "script",
+    {
+      "data-symphony": true,
+      dangerouslySetInnerHTML: { __html: script }
+    }
+  );
+};
+
+// src/core/scheduler.ts
+var scheduleMicrotask = (flush) => {
+  if (typeof queueMicrotask === "function") {
+    queueMicrotask(flush);
+    return;
+  }
+  Promise.resolve().then(flush);
+};
+var createScheduler = (scheduler) => {
+  if (!scheduler || scheduler === "microtask") {
+    return scheduleMicrotask;
+  }
+  if (scheduler === "sync") {
+    return (flush) => flush();
+  }
+  if (scheduler === "raf") {
+    return (flush) => {
+      if (typeof requestAnimationFrame === "function") {
+        requestAnimationFrame(() => flush());
+        return;
+      }
+      scheduleMicrotask(flush);
+    };
+  }
+  return scheduler;
+};
+
+// src/core/conductor.ts
+var defaultPersist = (value, config) => {
+  if (!config.storage) {
+    return;
+  }
+  const serialize = config.serialize ?? JSON.stringify;
+  config.storage.setItem(config.key, serialize(value));
+};
+var readPersist = (config) => {
+  if (!config.storage) {
+    return void 0;
+  }
+  const raw = config.storage.getItem(config.key);
+  if (!raw) {
+    return void 0;
+  }
+  const deserialize = config.deserialize ?? JSON.parse;
+  return deserialize(raw);
+};
+var now = () => Date.now();
+var isObject = (value) => typeof value === "object" && value !== null;
+var createDependencyOrder = (dependencies) => {
+  const indegree = /* @__PURE__ */ new Map();
+  const outgoing = /* @__PURE__ */ new Map();
+  dependencies.forEach((deps, key) => {
+    indegree.set(key, deps.length);
+    deps.forEach((dep) => {
+      if (!outgoing.has(dep)) {
+        outgoing.set(dep, []);
+      }
+      outgoing.get(dep)?.push(key);
+    });
+  });
+  const queue = [];
+  indegree.forEach((count, key) => {
+    if (count === 0) {
+      queue.push(key);
+    }
+  });
+  const order = [];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) {
+      continue;
+    }
+    order.push(current);
+    const children = outgoing.get(current) ?? [];
+    for (const child of children) {
+      const next = (indegree.get(child) ?? 0) - 1;
+      indegree.set(child, next);
+      if (next === 0) {
+        queue.push(child);
+      }
+    }
+  }
+  if (order.length !== dependencies.size) {
+    const cycle = [...dependencies.keys()].filter((key) => !order.includes(key));
+    throw new Error(
+      `Dependency cycle detected in sections: ${cycle.join(", ")}`
+    );
+  }
+  return order;
+};
+var resolveStorage = (persist) => {
+  if (!persist) {
+    return void 0;
+  }
+  if (persist.storage) {
+    return persist;
+  }
+  if (typeof window === "undefined") {
+    return { ...persist, storage: null };
+  }
+  return { ...persist, storage: window.localStorage };
+};
+var createConductor = (config) => {
+  const sections = /* @__PURE__ */ new Map();
+  const updates = /* @__PURE__ */ new Map();
+  const effects = /* @__PURE__ */ new Set();
+  const dependencies = /* @__PURE__ */ new Map();
+  const scheduler = createScheduler(config.scheduler);
+  const transactionHistory = [];
+  const transactionHistoryLimit = config.transactionHistoryLimit ?? 20;
+  const persistValue = (state, value) => {
+    if (!state.persist) {
+      return;
+    }
+    const persist = resolveStorage(state.persist);
+    if (!persist?.storage) {
+      return;
+    }
+    if (persist.throttleMs && persist.throttleMs > 0) {
+      if (state.persistTimer) {
+        clearTimeout(state.persistTimer);
+      }
+      state.persistTimer = setTimeout(() => {
+        defaultPersist(value, persist);
+      }, persist.throttleMs);
+      return;
+    }
+    defaultPersist(value, persist);
+  };
+  const hydrateValue = (state) => {
+    const persist = resolveStorage(state.persist);
+    if (!persist?.storage) {
+      return;
+    }
+    const stored = readPersist(persist);
+    if (stored !== void 0) {
+      state.value = stored;
+      state.adapter?.set(stored);
+    }
+  };
+  const bootstrapValues = (() => {
+    if (!config.bootstrap) {
+      return void 0;
+    }
+    if (typeof config.bootstrap === "function") {
+      return config.bootstrap();
+    }
+    return config.bootstrap;
+  })();
+  for (const definition of config.sections) {
+    if (sections.has(definition.key)) {
+      throw new Error(`Section with key "${definition.key}" already exists.`);
+    }
+    const dependsOn = definition.dependsOn ?? [];
+    const state = {
+      key: definition.key,
+      adapter: definition.source,
+      subscribers: /* @__PURE__ */ new Set(),
+      dependsOn,
+      persist: definition.persist,
+      value: definition.source.get()
+    };
+    sections.set(definition.key, state);
+    dependencies.set(definition.key, dependsOn);
+  }
+  const derivedDefinitions = config.derived ?? [];
+  for (const definition of derivedDefinitions) {
+    if (sections.has(definition.key)) {
+      throw new Error(`Section with key "${definition.key}" already exists.`);
+    }
+    const state = {
+      key: definition.key,
+      subscribers: /* @__PURE__ */ new Set(),
+      dependsOn: definition.inputs,
+      value: void 0,
+      derived: {
+        inputs: definition.inputs,
+        compute: definition.compute,
+        lastInputs: void 0
+      }
+    };
+    sections.set(definition.key, state);
+    dependencies.set(definition.key, definition.inputs);
+  }
+  const order = createDependencyOrder(dependencies);
+  for (const [key, state] of sections) {
+    if (bootstrapValues && key in bootstrapValues) {
+      const value = bootstrapValues[key];
+      state.value = value;
+      state.adapter?.set(value);
+      continue;
+    }
+    if (state.persist) {
+      hydrateValue(state);
+    }
+  }
+  const stagedChanges = /* @__PURE__ */ new Set();
+  const pendingNotifications = /* @__PURE__ */ new Set();
+  let scheduled = false;
+  let transactionDepth = 0;
+  let lastTransactionLabel;
+  const notifySubscribers = () => {
+    scheduled = false;
+    for (const key of pendingNotifications) {
+      const state = sections.get(key);
+      if (!state) {
+        continue;
+      }
+      for (const subscriber of state.subscribers) {
+        subscriber();
+      }
+    }
+    pendingNotifications.clear();
+  };
+  const scheduleNotify = (keys) => {
+    for (const key of keys) {
+      pendingNotifications.add(key);
+    }
+    if (scheduled) {
+      return;
+    }
+    scheduled = true;
+    scheduler(notifySubscribers);
+  };
+  const markChanged = (key) => {
+    stagedChanges.add(key);
+  };
+  const applyUpdate = (state, update) => {
+    if (update.type === "set") {
+      if (Object.is(state.value, update.value)) {
+        return false;
+      }
+      state.adapter?.set(update.value);
+      state.value = update.value;
+      return true;
+    }
+    if (state.adapter?.patch) {
+      if (isObject(state.value) && isObject(update.value)) {
+        const next = { ...state.value, ...update.value };
+        const changed = Object.keys(update.value).some(
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (k) => !Object.is(state.value[k], update.value[k])
+        );
+        if (!changed) {
+          return false;
+        }
+        state.adapter.patch(update.value);
+        state.value = next;
+        return true;
+      }
+      state.adapter.patch(update.value);
+      state.value = update.value;
+      return true;
+    }
+    if (isObject(state.value) && isObject(update.value)) {
+      const next = { ...state.value, ...update.value };
+      const changed = Object.keys(update.value).some(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (k) => !Object.is(state.value[k], update.value[k])
+      );
+      if (!changed) {
+        return false;
+      }
+      state.adapter?.set(next);
+      state.value = next;
+      return true;
+    }
+    throw new Error(`Section "${state.key}" does not support patch updates.`);
+  };
+  const computeDerived = (state) => {
+    if (!state.derived) {
+      return false;
+    }
+    const inputs = state.derived.inputs.map((key) => {
+      const inputState = sections.get(key);
+      if (!inputState) {
+        throw new Error(`Missing input section "${key}".`);
+      }
+      return inputState.value;
+    });
+    if (state.derived.lastInputs && inputs.every((value, index) => Object.is(value, state.derived?.lastInputs?.[index]))) {
+      return false;
+    }
+    const next = state.derived.compute(...inputs);
+    const changed = !Object.is(state.value, next);
+    state.value = next;
+    state.derived.lastInputs = inputs;
+    return changed;
+  };
+  for (const key of order) {
+    const state = sections.get(key);
+    if (!state?.derived) {
+      continue;
+    }
+    computeDerived(state);
+  }
+  const runEffects = (changedKeys) => {
+    if (effects.size === 0) {
+      return;
+    }
+    const api = {
+      get: (key) => getSectionValue(key),
+      set: (key, value) => setSectionValue(key, value),
+      patch: (key, value) => patchSectionValue(key, value),
+      transaction: (fn, label) => transaction(fn, label)
+    };
+    for (const effect2 of effects) {
+      if (!effect2.when.some((key) => changedKeys.includes(key))) {
+        continue;
+      }
+      const limit = effect2.maxDepth ?? 5;
+      if (transactionDepth > limit) {
+        throw new Error(
+          `Effect depth exceeded while running effect for sections: ${effect2.when.join(", ")}`
+        );
+      }
+      effect2.run(api);
+    }
+  };
+  const commit = () => {
+    if (updates.size === 0 && stagedChanges.size === 0) {
+      return;
+    }
+    const changedKeys = [];
+    for (const key of order) {
+      const state = sections.get(key);
+      if (!state) {
+        continue;
+      }
+      const update = updates.get(key);
+      if (update && !state.derived) {
+        const changed = applyUpdate(state, update);
+        if (changed) {
+          persistValue(state, state.value);
+          changedKeys.push(key);
+        }
+        updates.delete(key);
+      }
+      if (state.derived) {
+        const derivedChanged = computeDerived(state);
+        if (derivedChanged) {
+          changedKeys.push(key);
+        }
+      }
+    }
+    if (changedKeys.length > 0) {
+      scheduleNotify(changedKeys);
+      transactionHistory.unshift({
+        label: lastTransactionLabel,
+        touched: [...new Set(changedKeys)],
+        timestamp: now()
+      });
+      if (transactionHistory.length > transactionHistoryLimit) {
+        transactionHistory.length = transactionHistoryLimit;
+      }
+    }
+    stagedChanges.clear();
+    lastTransactionLabel = void 0;
+    runEffects(changedKeys);
+  };
+  const beginTransaction = (label) => {
+    transactionDepth += 1;
+    if (label) {
+      lastTransactionLabel = label;
+    }
+  };
+  const endTransaction = () => {
+    transactionDepth -= 1;
+    if (transactionDepth === 0) {
+      commit();
+    }
+  };
+  const transaction = (fn, label) => {
+    beginTransaction(label);
+    try {
+      fn();
+    } finally {
+      endTransaction();
+    }
+  };
+  const setSectionValue = (key, value) => {
+    if (!sections.has(key)) {
+      throw new Error(`Unknown section "${key}".`);
+    }
+    if (transactionDepth === 0) {
+      return transaction(() => setSectionValue(key, value));
+    }
+    const state = sections.get(key);
+    if (state?.derived) {
+      throw new Error(`Cannot set derived section "${key}".`);
+    }
+    updates.set(key, { type: "set", value });
+    markChanged(key);
+  };
+  const patchSectionValue = (key, value) => {
+    if (!sections.has(key)) {
+      throw new Error(`Unknown section "${key}".`);
+    }
+    if (transactionDepth === 0) {
+      return transaction(() => patchSectionValue(key, value));
+    }
+    const state = sections.get(key);
+    if (state?.derived) {
+      throw new Error(`Cannot patch derived section "${key}".`);
+    }
+    updates.set(key, { type: "patch", value });
+    markChanged(key);
+  };
+  const getSectionValue = (key) => {
+    const state = sections.get(key);
+    if (!state) {
+      throw new Error(`Unknown section "${key}".`);
+    }
+    return state.value;
+  };
+  const subscribe = (key, cb) => {
+    const state = sections.get(key);
+    if (!state) {
+      throw new Error(`Unknown section "${key}".`);
+    }
+    state.subscribers.add(cb);
+    return () => {
+      state.subscribers.delete(cb);
+    };
+  };
+  const getSection = (key) => {
+    return {
+      get: () => getSectionValue(key),
+      set: (next) => setSectionValue(key, next),
+      patch: (next) => patchSectionValue(key, next),
+      subscribe: (cb) => subscribe(key, cb)
+    };
+  };
+  const effect = (definition) => {
+    effects.add(definition);
+    return () => effects.delete(definition);
+  };
+  const getSnapshot = () => {
+    const snapshot = { sections: {}, transactions: [] };
+    for (const [key, state] of sections) {
+      snapshot.sections[key] = state.value;
+    }
+    snapshot.transactions = [...transactionHistory];
+    return snapshot;
+  };
+  const destroy = () => {
+    sections.forEach((state) => {
+      state.adapter?.destroy?.();
+      if (state.persistTimer) {
+        clearTimeout(state.persistTimer);
+      }
+      state.subscribers.clear();
+    });
+    sections.clear();
+    updates.clear();
+    effects.clear();
+  };
+  return {
+    getSection,
+    getSectionValue,
+    subscribe,
+    transaction,
+    effect,
+    getSnapshot,
+    destroy
+  };
+};
+
+// src/react/createSymphony.ts
+var createSymphony = (config) => {
+  const sectionEntries = Object.values(config.sections);
+  const sections = [];
+  const derived = [];
+  for (const entry of sectionEntries) {
+    if ("source" in entry) {
+      sections.push(entry);
+    } else {
+      derived.push(entry);
+    }
+  }
+  const conductor = createConductor({
+    sections,
+    derived,
+    scheduler: config.scheduler,
+    bootstrap: config.bootstrap
+  });
+  return {
+    conductor,
+    Provider: SymphonyProvider,
+    useSection: (key) => useSection(String(key)),
+    useSelector: (key, selector, equality) => useSelector(String(key), selector, equality)
+  };
+};
+
+export { SymphonyProvider, SymphonyScript, createSymphony, useConductor, useSection, useSelector };
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map