@excom/kit-utils 0.1.0

package/form.ts

@@ -0,0 +1,99 @@
+import { isNumber } from "./common";
+import * as pathval from "pathval";
+
+export function parseFormInputValue(
+  root,
+  input: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement | undefined,
+  key,
+  value
+) {
+  if (input) {
+    if (["number", "range"].includes(input.type)) {
+      return Number(value);
+    }
+    if (input.type === "checkbox") {
+      if (typeof value === "string" && !["on", "off"].includes(value)) {
+        return Array.from(root.querySelectorAll(`[name="${key}"]:checked`)).map(
+          (input) => {
+            return (input as HTMLInputElement).value;
+          }
+        );
+      } else {
+        return (input as HTMLInputElement).checked;
+      }
+    }
+    if (input.type === "radio") {
+      const _input = root.querySelector(`[name="${key}"]:checked`);
+      return _input?.checked ? value : null;
+    }
+    if (input instanceof HTMLSelectElement && input.multiple) {
+      return Array.from(input.options)
+        .filter((option) => option.selected)
+        .map((option) => option.value);
+    }
+    return value;
+  }
+  return value;
+}
+
+type FormControl = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+/**
+ * Serialize a form to a nested JSON object. Field names are paths
+ * (`address.city`, `tags[]`); values are typed from the control
+ * (`number` / `range` → number, checkbox → boolean or checked-values array,
+ * multi-select → array). Form-associated controls (`form="id"`) count like
+ * descendants, as they do for `FormData`.
+ *
+ * Controls are indexed once by `name` from `form.elements`, so a form with
+ * thousands of fields serializes in one pass (no per-field selector query).
+ */
+export function formToJson(form: HTMLFormElement) {
+  const json = {};
+  const formData = new FormData(form);
+  /* name → controls, document order. `form.elements` also lists
+   * controls associated via `form=`, matching `FormData`. */
+  const byName = new Map<string, FormControl[]>();
+  for (const control of Array.from(form.elements) as FormControl[]) {
+    const name = control.getAttribute("name");
+    if (!name) continue;
+    const list = byName.get(name);
+    if (list) list.push(control);
+    else byName.set(name, [control]);
+  }
+  const formEntries: Array<[string, FormDataEntryValue | string]> = [
+    ...formData.entries(),
+    // include unchecked checkboxes
+    ...Array.from(
+      form.querySelectorAll<HTMLInputElement>(
+        "input[name][type='checkbox']:not([value]):not(:checked)"
+      )
+    ).map((input): [string, string] => [
+      input.name,
+      input.checked ? input.value : "off",
+    ]),
+  ];
+  const arrayPaths = {};
+  formEntries.forEach(([key, value]) => {
+    if (key?.includes("[]")) {
+      if (isNumber(arrayPaths[key])) {
+        arrayPaths[key] += 1;
+      } else {
+        arrayPaths[key] = 0;
+      }
+      const arrayKey = key.replace("[]", `[${arrayPaths[key]}]`);
+      const found = byName.get(key)?.find((control) => control.value === value);
+      const parsedValue = parseFormInputValue(form, found, key, value);
+      pathval.setPathValue(json, arrayKey, parsedValue);
+    } else if (key) {
+      const parsedValue = parseFormInputValue(
+        form,
+        byName.get(key)?.[0],
+        key,
+        value
+      );
+      pathval.setPathValue(json, key, parsedValue);
+    }
+  });
+  return json;
+}

package/index.ts

@@ -0,0 +1,9 @@
+export * from "./batch-manager";
+export * from "./common";
+export * from "./dom";
+export * from "./fetching";
+export * from "./form";
+export * from "./loop-guard";
+export * from "./property";
+export * from "./queue-manager";
+export * from "./url";

package/load-dependency.ts

@@ -0,0 +1,40 @@
+window.__DEPENDENCY_PROMISES__ = window.__DEPENDENCY_PROMISES__ || {};
+
+type TDepGlobalName = string;
+declare global {
+  interface Window {
+    __DEPENDENCY_PROMISES__: Record<TDepGlobalName, Promise<any> | undefined>;
+  }
+}
+
+/* Load an ESM module or a UMD script; return the export / global. */
+export async function loadDependency<T = any>(
+  type: "esm" | "umd",
+  uri: string,
+  globalName?: TDepGlobalName
+): Promise<T> {
+  if (type === "esm") {
+    return import(/* @vite-ignore */ uri);
+  } else if (type === "umd" && globalName) {
+    if (window[globalName]) {
+      return window[globalName];
+    }
+    if (!window.__DEPENDENCY_PROMISES__[globalName]) {
+      window.__DEPENDENCY_PROMISES__[globalName] = new Promise(
+        (resolve, reject) => {
+          const script = document.createElement("script");
+          script.src = uri;
+          document.body.appendChild(script);
+          script.onload = () => resolve(window[globalName]);
+          script.onerror = () =>
+            reject(new Error(`Failed to load dependency: ${globalName}`));
+        }
+      );
+    }
+    return window.__DEPENDENCY_PROMISES__[globalName]!;
+  } else {
+    throw new Error(
+      `Invalid dependency load request: ${type} | ${uri} | ${globalName}`
+    );
+  }
+}

package/loop-guard.ts

@@ -0,0 +1,187 @@
+/**
+ * Cuts runaway write cycles after a fixed hop count. Shared by Quark,
+ * Neutron, and any other DOM writer. Depth is carried by address, so
+ * neither engine needs to know about the other.
+ *
+ * - **context**: a reaction (`run(inherited, fn)` at `max(current(), inherited)`).
+ * - **write**: `write(target, name, fn)` at `current() + 1`, stamped on
+ *   `(target, name)` (attribute, property, binding, or `"content"`).
+ * - **trigger**: the next reaction inherits `depthOf(target, name)`.
+ *
+ * Stamps last this task + its microtasks. A later external write (input,
+ * timer, fetch, app JS) starts over at depth 0. Past `limit` the write is
+ * dropped and reported once; the document is left as-is.
+ *
+ * Unguarded writes (`setAttribute` in app JS) neither stamp nor drop.
+ * A loop that never hits `write()` is invisible; one that does is cut there.
+ */
+
+export type LoopGuardTripKind = "depth" | "batch";
+
+export interface LoopGuardTrip {
+  /**
+   * `"depth"`: a causal chain of writes exceeded `limit` hops (the write
+   * was dropped). `"batch"`: one `BatchManager` handler re-ran more than
+   * `limit` times inside a single synchronous flush (the queue was
+   * dropped).
+   */
+  kind: LoopGuardTripKind;
+  /** The element / object the dropped write targeted. */
+  target: object;
+  /** Attribute, property or binding name (`"content"` for child insertions). */
+  name: string;
+  /** Depth (or run count) that crossed the limit. */
+  depth: number;
+  limit: number;
+  /** Human-readable summary, also passed to the log function. */
+  message: string;
+}
+
+export type LoopGuardListener = (trip: LoopGuardTrip) => void;
+export type LoopGuardLog = (message: string, trip: LoopGuardTrip) => void;
+
+interface Stamp {
+  depth: number;
+  epoch: number;
+}
+
+const DEFAULT_LIMIT = 50;
+const defaultLog: LoopGuardLog = (message) => console.error(message);
+
+const STAMPS = new WeakMap<object, Map<string, Stamp>>();
+const stack: number[] = [];
+const listeners = new Set<LoopGuardListener>();
+/** name → epoch of its last report; one report per name per task. */
+const reported = new Map<string, number>();
+let epoch = 1;
+let bumpScheduled = false;
+let limit = DEFAULT_LIMIT;
+let log: LoopGuardLog = defaultLog;
+
+/** Stamps expire at the next macrotask; one timer per task, only when something was stamped. */
+const scheduleEpochBump = () => {
+  if (bumpScheduled) return;
+  bumpScheduled = true;
+  setTimeout(() => {
+    bumpScheduled = false;
+    epoch++;
+  }, 0);
+};
+
+const describeTarget = (target: object) =>
+  target instanceof Element
+    ? `<${target.localName}${target.id ? `#${target.id}` : ""}>`
+    : (target?.constructor?.name ?? typeof target);
+
+export const LoopGuard = {
+  /** Maximum causal depth (and maximum handler re-runs per batch flush). */
+  get limit(): number {
+    return limit;
+  },
+
+  /** Adjust the limit and/or the log function (defaults: 50, `console.error`). */
+  configure(options: { limit?: number; log?: LoopGuardLog } = {}): void {
+    if (typeof options.limit === "number" && options.limit > 0) {
+      limit = Math.floor(options.limit);
+    }
+    if (options.log) log = options.log;
+  },
+
+  /** Depth of the innermost open context (0 outside any context). */
+  current(): number {
+    return stack.length ? stack[stack.length - 1] : 0;
+  },
+
+  /**
+   * Depth stamped on `(target, name)` by a guarded write earlier in this
+   * task, or 0 when nothing (or something in an earlier task) wrote it.
+   * Triggers call this to inherit the chain they continue.
+   */
+  depthOf(target: object, name: string): number {
+    const stamp = STAMPS.get(target)?.get(name);
+    return stamp && stamp.epoch === epoch ? stamp.depth : 0;
+  },
+
+  /**
+   * Open a context at `max(current(), inherited)` for the duration of `fn`.
+   * Pass a depth captured with `current()` to carry a context across an
+   * async boundary the engine itself introduces (a deferred paint, a
+   * `setTimeout(0)` effect).
+   */
+  run<T>(inherited: number, fn: () => T): T {
+    stack.push(Math.max(LoopGuard.current(), inherited));
+    try {
+      return fn();
+    } finally {
+      stack.pop();
+    }
+  },
+
+  /**
+   * Record that `(target, name)` was written at `depth` (default: the depth
+   * a `write()` would use) without applying a limit. For writers that want
+   * to be *visible* to the chain but never dropped.
+   */
+  stamp(target: object, name: string, depth = LoopGuard.current() + 1): void {
+    let names = STAMPS.get(target);
+    if (!names) STAMPS.set(target, (names = new Map()));
+    names.set(name, { depth, epoch });
+    scheduleEpochBump();
+  },
+
+  /**
+   * Perform a write as the next hop of the current chain: stamps
+   * `(target, name)` at `current() + 1`, then runs `fn` and returns its
+   * result. Past the limit the write is **not** performed, the trip is
+   * reported, and `false` is returned.
+   */
+  write<T>(target: object, name: string, fn: () => T): T | false {
+    const depth = LoopGuard.current() + 1;
+    if (depth > limit) {
+      LoopGuard.report({
+        kind: "depth",
+        target,
+        name,
+        depth,
+        limit,
+        message: `Loop guard: a chain of ${depth} dependent writes reached "${name}" on ${describeTarget(target)} — likely an infinite loop between rules, element effects or events; the write was dropped.`,
+      });
+      return false;
+    }
+    LoopGuard.stamp(target, name, depth);
+    return fn();
+  },
+
+  /**
+   * Report a trip: logs once per name per task and notifies listeners
+   * (every time). Engines use listeners to publish to DevTools.
+   */
+  report(trip: LoopGuardTrip): void {
+    if (reported.get(trip.name) !== epoch) {
+      reported.set(trip.name, epoch);
+      scheduleEpochBump();
+      log(trip.message, trip);
+    }
+    listeners.forEach((listener) => listener(trip));
+  },
+
+  /** Subscribe to trips; returns the unsubscribe function. */
+  onTrip(listener: LoopGuardListener): () => void {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  },
+
+  /**
+   * Test helper: forget open contexts and stamps, restore the default
+   * limit and log. Listeners are kept (engines register theirs once).
+   */
+  reset(): void {
+    stack.length = 0;
+    reported.clear();
+    epoch++;
+    limit = DEFAULT_LIMIT;
+    log = defaultLog;
+  },
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@excom/kit-utils",
+  "version": "0.1.0",
+  "description": "kit-utils library",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "pathval": "^2.0.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/kit-utils"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/kit-utils/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "kit-utils"
+  ],
+  "excom": {
+    "documented": false,
+    "packageType": "library"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs"
+  }
+}

package/property.ts

@@ -0,0 +1,225 @@
+/**
+ * Observable properties. Neutron defines them with
+ * `defineObservableProperty`; Quark subscribes with `observeProperty`
+ * (any element: Neutron, third-party, or native).
+ *
+ * One own accessor per (target, name), always outermost:
+ * - `observeProperty` wraps whatever is there (own accessor, data
+ *   property, or inherited prototype accessor).
+ * - `defineObservableProperty` installs the *base* getter/setter. If a
+ *   wrapper is already on, the base is swapped under it so subscriptions
+ *   survive upgrade.
+ *
+ * Notify after the base setter, only on `!==`. In-place object mutation
+ * is not a write. Last subscriber off restores the base if the wrapper
+ * is still the own descriptor.
+ */
+
+import { LoopGuard } from "./loop-guard";
+
+export type PropertyObserver = (value: unknown, oldValue: unknown) => void;
+
+export interface BaseDescriptor {
+  get?: (this: object) => unknown;
+  set?: (this: object, value: unknown) => void;
+  enumerable?: boolean;
+}
+
+interface Entry {
+  base: BaseDescriptor;
+  /**
+   * How to put the property back when the wrapper is removed: an own
+   * descriptor to redefine, `"absent"` when nothing existed before (the
+   * assigned value, if any, becomes a plain data property), or `null` for
+   * an inherited accessor (the own shadow is simply removed).
+   */
+  restore: PropertyDescriptor | "absent" | null;
+  subscribers: Set<PropertyObserver>;
+  get: () => unknown;
+  set: (value: unknown) => void;
+}
+
+const REGISTRY = new WeakMap<object, Map<string, Entry>>();
+
+const entries = (target: object): Map<string, Entry> => {
+  let map = REGISTRY.get(target);
+  if (!map) REGISTRY.set(target, (map = new Map()));
+  return map;
+};
+
+const findDescriptor = (
+  target: object,
+  name: string
+): { descriptor: PropertyDescriptor; own: boolean } | null => {
+  const own = Object.getOwnPropertyDescriptor(target, name);
+  if (own) return { descriptor: own, own: true };
+  for (
+    let proto = Object.getPrototypeOf(target);
+    proto;
+    proto = Object.getPrototypeOf(proto)
+  ) {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, name);
+    if (descriptor) return { descriptor, own: false };
+  }
+  return null;
+};
+
+const isDataDescriptor = (d: PropertyDescriptor) =>
+  "value" in d || "writable" in d;
+
+/** A base that stores in a closure slot (for data properties / absent). */
+const slotBase = (value: unknown, writable: boolean): BaseDescriptor => {
+  let slot = value;
+  return {
+    get: () => slot,
+    set: writable
+      ? (next) => {
+          slot = next;
+        }
+      : undefined,
+    enumerable: true,
+  };
+};
+
+/** The wrapper's own descriptor, identity is how we recognize ourselves. */
+const isWrapper = (target: object, name: string, entry: Entry) => {
+  const own = Object.getOwnPropertyDescriptor(target, name);
+  return !!own && own.get === entry.get && own.set === entry.set;
+};
+
+const install = (target: object, name: string): Entry | null => {
+  const found = findDescriptor(target, name);
+  let base: BaseDescriptor;
+  let restore: Entry["restore"];
+  if (!found) {
+    base = slotBase(undefined, true);
+    restore = "absent";
+  } else if (isDataDescriptor(found.descriptor)) {
+    if (found.descriptor.writable === false) return null;
+    base = slotBase(found.descriptor.value, true);
+    base.enumerable = found.descriptor.enumerable;
+    // an own data property is restored with its current value; an
+    // inherited one (rare) simply gets the own shadow removed
+    restore = found.own ? { ...found.descriptor } : null;
+  } else {
+    if (!found.descriptor.set) return null;
+    base = {
+      get: found.descriptor.get,
+      set: found.descriptor.set,
+      enumerable: found.descriptor.enumerable,
+    };
+    restore = found.own ? { ...found.descriptor } : null;
+  }
+  if (found?.own && found.descriptor.configurable === false) return null;
+  const entry: Entry = {
+    base,
+    restore,
+    subscribers: new Set(),
+    get() {
+      return entry.base.get?.call(target);
+    },
+    set(value: unknown) {
+      const old = entry.base.get?.call(target);
+      // an observed assignment is one causal hop; past the loop guard's
+      // limit it is dropped (the chain that led here is a runaway loop)
+      const applied = LoopGuard.write(target, name, () => {
+        entry.base.set?.call(target, value);
+        return true;
+      });
+      if (applied === false) return;
+      const next = entry.base.get?.call(target);
+      if (next !== old) {
+        entry.subscribers.forEach((subscriber) => subscriber(next, old));
+      }
+    },
+  };
+  Object.defineProperty(target, name, {
+    get: entry.get,
+    set: entry.set,
+    enumerable: base.enumerable ?? false,
+    configurable: true,
+  });
+  entries(target).set(name, entry);
+  return entry;
+};
+
+const uninstall = (target: object, name: string, entry: Entry) => {
+  entries(target).delete(name);
+  if (!isWrapper(target, name, entry)) return; // someone redefined it
+  const restore = entry.restore;
+  if (!restore || restore === "absent") {
+    const value = entry.base.get?.call(target);
+    delete (target as Record<string, unknown>)[name];
+    if (restore === "absent" && value !== undefined) {
+      (target as Record<string, unknown>)[name] = value;
+    }
+    return;
+  }
+  if (isDataDescriptor(restore)) {
+    Object.defineProperty(target, name, {
+      ...restore,
+      value: entry.base.get?.call(target),
+    });
+  } else {
+    Object.defineProperty(target, name, {
+      get: entry.base.get,
+      set: entry.base.set,
+      enumerable: restore.enumerable,
+      configurable: true,
+    });
+  }
+};
+
+/**
+ * Observe assignments to `target[name]`. Returns an unsubscribe function.
+ * Read-only properties (no setter / non-writable) cannot change by
+ * assignment, so nothing is installed and the returned function is a no-op.
+ */
+export const observeProperty = (
+  target: object,
+  name: string,
+  observer: PropertyObserver
+): (() => void) => {
+  const entry = entries(target).get(name) ?? install(target, name);
+  if (!entry) return () => {};
+  entry.subscribers.add(observer);
+  return () => {
+    if (!entry.subscribers.delete(observer)) return;
+    if (entry.subscribers.size === 0) uninstall(target, name, entry);
+  };
+};
+
+/**
+ * Define the storage-owning accessor of `target[name]`. Keeps an installed
+ * observer wrapper on top (its base is swapped), so an element upgrading
+ * after a sheet subscribed keeps that subscription.
+ */
+export const defineObservableProperty = (
+  target: object,
+  name: string,
+  descriptor: BaseDescriptor
+): void => {
+  const entry = entries(target).get(name);
+  if (entry && isWrapper(target, name, entry)) {
+    entry.base = descriptor;
+    // no slot to keep: the new base owns storage; nothing to restore to
+    // but the base itself
+    entry.restore = {
+      get: descriptor.get,
+      set: descriptor.set,
+      enumerable: descriptor.enumerable ?? false,
+      configurable: true,
+    };
+    return;
+  }
+  Object.defineProperty(target, name, {
+    get: descriptor.get,
+    set: descriptor.set,
+    enumerable: descriptor.enumerable ?? false,
+    configurable: true,
+  });
+};
+
+/** Whether `target[name]` currently has observers. */
+export const isObservedProperty = (target: object, name: string): boolean =>
+  (REGISTRY.get(target)?.get(name)?.subscribers.size ?? 0) > 0;