@weasel-js/registry 1.9.3 → 1.9.4

package/dist/index.d.ts

@@ -63,4 +63,32 @@ interface Reflectable<V, K = string> extends Reflection<V, K> {
  */
 declare function createReflectable<V, K = string>(): Reflectable<V, K>;
 
-export { type Reflectable, type ReflectedEntry, type Reflection, type RegisterOptions, type Registrant, createReflectable };
+/** A set of listeners and the one way the kit notifies them. See {@link createEmitter}. */
+interface Emitter<TArgs extends unknown[] = []> {
+    /** Add `listener`; a listener already held is held once. Returns the unsubscribe. */
+    subscribe(listener: (...args: TArgs) => void): () => void;
+    /** Call every listener held when the call began. */
+    emit(...args: TArgs): void;
+    /** How many listeners are held. */
+    readonly size: number;
+}
+/**
+ * A subscribe/notify pair with stated semantics, for a store to build on
+ * instead of keeping its own listener set:
+ *
+ * - `emit` walks the listeners held when it began, in subscription order. One
+ *   that subscribes during a pass waits for the next; one unsubscribed before
+ *   its turn is not called.
+ * - A listener that throws does not stop the others, and does not throw into
+ *   whatever caused the notify: the error goes to `console.error`.
+ */
+declare function createEmitter<TArgs extends unknown[] = []>(): Emitter<TArgs>;
+
+/** Whether `proto` is the prototype a plain object has: `null`, or some
+ *  realm's `Object.prototype`. Comparing against this realm's alone misses
+ *  objects made in an iframe, a VM context, or by `structuredClone` under jsdom. */
+declare function isPlainPrototype(proto: object | null): boolean;
+/** Whether `value` is a plain object — a literal or `Object.create(null)` — from any realm. */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+
+export { type Emitter, type Reflectable, type ReflectedEntry, type Reflection, type RegisterOptions, type Registrant, createEmitter, createReflectable, isPlainObject, isPlainPrototype };

package/dist/index.js

@@ -1,18 +1,38 @@
+// src/emitter.ts
+function createEmitter() {
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    emit(...args) {
+      for (const listener of [...listeners]) {
+        if (!listeners.has(listener)) continue;
+        try {
+          listener(...args);
+        } catch (err) {
+          console.error("weasel: a subscriber threw", err);
+        }
+      }
+    },
+    get size() {
+      return listeners.size;
+    }
+  };
+}
+
 // src/reflectable.ts
 function createReflectable() {
   const stacks = /* @__PURE__ */ new Map();
-  const listeners = /* @__PURE__ */ new Set();
+  const listeners = createEmitter();
   let version = 0;
   let snapshot = null;
   function changed() {
     version++;
-    for (const listener of listeners) {
-      try {
-        listener();
-      } catch (err) {
-        console.error("weasel registry: subscriber threw", err);
-      }
-    }
+    listeners.emit();
   }
   const reflection = {
     get: (key) => stacks.get(key)?.at(-1)?.value,
@@ -32,12 +52,7 @@ function createReflectable() {
       snapshot = { version, entries: Object.freeze(entries) };
       return snapshot.entries;
     },
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
+    subscribe: listeners.subscribe,
     getVersion: () => version
   };
   return {
@@ -82,6 +97,14 @@ function createReflectable() {
   };
 }
 
-export { createReflectable };
+// src/isPlainObject.ts
+function isPlainPrototype(proto) {
+  return proto === Object.prototype || proto === null || Object.getPrototypeOf(proto) === null;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && isPlainPrototype(Object.getPrototypeOf(value));
+}
+
+export { createEmitter, createReflectable, isPlainObject, isPlainPrototype };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/reflectable.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/** One registrant of a key: its value and, when the registrant named one, where it came from. */\nexport interface Registrant<V> {\n  readonly value: V;\n  readonly source: string | undefined;\n}\n\n/** One key as a reflection reports it. */\nexport interface ReflectedEntry<V, K = string> extends Registrant<V> {\n  readonly key: K;\n  /** The registrants this one displaced, oldest first. Non-empty means two\n   *  registrants claimed one key — a conflict, resolved newest-wins. */\n  readonly shadowed: readonly Registrant<V>[];\n}\n\n/**\n * The read-only face of a registry: what is registered, what displaced what,\n * and a way to hear about changes. Every kit registry that embeds a\n * {@link Reflectable} hands this out, so a debug overlay or a conflict check\n * can walk any of them the same way.\n *\n * `subscribe` and `getVersion` are shaped for `useSyncExternalStore`; so is\n * `entries`, which returns the same frozen array until the next change.\n */\nexport interface Reflection<V, K = string> {\n  get(key: K): V | undefined;\n  has(key: K): boolean;\n  /** Every key's live registrant, in the order each key was first registered. */\n  entries(): readonly ReflectedEntry<V, K>[];\n  /** Called after every change. Returns the unsubscribe. */\n  subscribe(listener: () => void): () => void;\n  /** Advances on every change. */\n  getVersion(): number;\n}\n\n/** Options for {@link Reflectable.push} and {@link Reflectable.set}. */\nexport interface RegisterOptions {\n  /** Who registered this — `'kit'`, a package, a plugin id. Reported, never interpreted. */\n  source?: string;\n}\n\n/**\n * A keyed store that keeps its own {@link Reflection}. The registry owning it\n * writes through `push` / `set` / `delete` and hands out `reflection`.\n */\nexport interface Reflectable<V, K = string> extends Reflection<V, K> {\n  /** Register `value` over whatever `key` holds and return its release.\n   *  Registrants stack, newest live: releasing the live one uncovers the one\n   *  it displaced, and releasing a displaced one removes only it. Double-release safe. */\n  push(key: K, value: V, options?: RegisterOptions): () => void;\n  /** Replace `key`'s live registrant in place, the way `Map.set` does — for\n   *  registries where a second registration means \"newer version\", not\n   *  \"override\". Records no conflict. */\n  set(key: K, value: V, options?: RegisterOptions): void;\n  /** Drop every registrant of `key`. Returns whether there was one. */\n  delete(key: K): boolean;\n  clear(): void;\n  /** Announce a change the store cannot see — a registered value mutated in place. */\n  bump(): void;\n  /** This store as a {@link Reflection}, with no write methods on it. */\n  readonly reflection: Reflection<V, K>;\n}\n\n/**\n * Create a keyed store with a uniform reflection surface.\n *\n * Deliberately only the cross-cutting part of a registry: validation, lookup\n * fallbacks and lifecycle stay with the registry that embeds it.\n */\nexport function createReflectable<V, K = string>(): Reflectable<V, K> {\n  const stacks = new Map<K, Registrant<V>[]>();\n  const listeners = new Set<() => void>();\n  let version = 0;\n  let snapshot: { version: number; entries: readonly ReflectedEntry<V, K>[] } | null = null;\n\n  function changed(): void {\n    version++;\n    for (const listener of listeners) {\n      try {\n        listener();\n      } catch (err) {\n        console.error('weasel registry: subscriber threw', err);\n      }\n    }\n  }\n\n  const reflection: Reflection<V, K> = {\n    get: (key) => stacks.get(key)?.at(-1)?.value,\n    has: (key) => stacks.has(key),\n    entries() {\n      if (snapshot?.version === version) return snapshot.entries;\n      const entries: ReflectedEntry<V, K>[] = [];\n      for (const [key, stack] of stacks) {\n        const live = stack.at(-1)!;\n        entries.push(Object.freeze({\n          key, value: live.value, source: live.source, shadowed: Object.freeze(stack.slice(0, -1)),\n        }));\n      }\n      snapshot = { version, entries: Object.freeze(entries) };\n      return snapshot.entries;\n    },\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => { listeners.delete(listener); };\n    },\n    getVersion: () => version,\n  };\n\n  return {\n    ...reflection,\n    reflection,\n    push(key, value, options) {\n      const registrant: Registrant<V> = Object.freeze({ value, source: options?.source });\n      const stack = stacks.get(key);\n      if (stack) stack.push(registrant);\n      else stacks.set(key, [registrant]);\n      changed();\n      let released = false;\n      return () => {\n        if (released) return;\n        released = true;\n        const cur = stacks.get(key);\n        const i = cur ? cur.lastIndexOf(registrant) : -1;\n        if (i === -1) return;\n        cur!.splice(i, 1);\n        if (cur!.length === 0) stacks.delete(key);\n        changed();\n      };\n    },\n    set(key, value, options) {\n      const registrant: Registrant<V> = Object.freeze({ value, source: options?.source });\n      const stack = stacks.get(key);\n      if (stack) stack[stack.length - 1] = registrant;\n      else stacks.set(key, [registrant]);\n      changed();\n    },\n    delete(key) {\n      if (!stacks.delete(key)) return false;\n      changed();\n      return true;\n    },\n    clear() {\n      if (stacks.size === 0) return;\n      stacks.clear();\n      changed();\n    },\n    bump: changed,\n  };\n}\n"]}
+{"version":3,"sources":["../src/emitter.ts","../src/reflectable.ts","../src/isPlainObject.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/** A set of listeners and the one way the kit notifies them. See {@link createEmitter}. */\nexport interface Emitter<TArgs extends unknown[] = []> {\n  /** Add `listener`; a listener already held is held once. Returns the unsubscribe. */\n  subscribe(listener: (...args: TArgs) => void): () => void;\n  /** Call every listener held when the call began. */\n  emit(...args: TArgs): void;\n  /** How many listeners are held. */\n  readonly size: number;\n}\n\n/**\n * A subscribe/notify pair with stated semantics, for a store to build on\n * instead of keeping its own listener set:\n *\n * - `emit` walks the listeners held when it began, in subscription order. One\n *   that subscribes during a pass waits for the next; one unsubscribed before\n *   its turn is not called.\n * - A listener that throws does not stop the others, and does not throw into\n *   whatever caused the notify: the error goes to `console.error`.\n */\nexport function createEmitter<TArgs extends unknown[] = []>(): Emitter<TArgs> {\n  const listeners = new Set<(...args: TArgs) => void>();\n  return {\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => { listeners.delete(listener); };\n    },\n    emit(...args) {\n      for (const listener of [...listeners]) {\n        if (!listeners.has(listener)) continue;\n        try {\n          listener(...args);\n        } catch (err) {\n          console.error('weasel: a subscriber threw', err);\n        }\n      }\n    },\n    get size() {\n      return listeners.size;\n    },\n  };\n}\n","import { createEmitter } from './emitter';\n\n/** One registrant of a key: its value and, when the registrant named one, where it came from. */\nexport interface Registrant<V> {\n  readonly value: V;\n  readonly source: string | undefined;\n}\n\n/** One key as a reflection reports it. */\nexport interface ReflectedEntry<V, K = string> extends Registrant<V> {\n  readonly key: K;\n  /** The registrants this one displaced, oldest first. Non-empty means two\n   *  registrants claimed one key — a conflict, resolved newest-wins. */\n  readonly shadowed: readonly Registrant<V>[];\n}\n\n/**\n * The read-only face of a registry: what is registered, what displaced what,\n * and a way to hear about changes. Every kit registry that embeds a\n * {@link Reflectable} hands this out, so a debug overlay or a conflict check\n * can walk any of them the same way.\n *\n * `subscribe` and `getVersion` are shaped for `useSyncExternalStore`; so is\n * `entries`, which returns the same frozen array until the next change.\n */\nexport interface Reflection<V, K = string> {\n  get(key: K): V | undefined;\n  has(key: K): boolean;\n  /** Every key's live registrant, in the order each key was first registered. */\n  entries(): readonly ReflectedEntry<V, K>[];\n  /** Called after every change. Returns the unsubscribe. */\n  subscribe(listener: () => void): () => void;\n  /** Advances on every change. */\n  getVersion(): number;\n}\n\n/** Options for {@link Reflectable.push} and {@link Reflectable.set}. */\nexport interface RegisterOptions {\n  /** Who registered this — `'kit'`, a package, a plugin id. Reported, never interpreted. */\n  source?: string;\n}\n\n/**\n * A keyed store that keeps its own {@link Reflection}. The registry owning it\n * writes through `push` / `set` / `delete` and hands out `reflection`.\n */\nexport interface Reflectable<V, K = string> extends Reflection<V, K> {\n  /** Register `value` over whatever `key` holds and return its release.\n   *  Registrants stack, newest live: releasing the live one uncovers the one\n   *  it displaced, and releasing a displaced one removes only it. Double-release safe. */\n  push(key: K, value: V, options?: RegisterOptions): () => void;\n  /** Replace `key`'s live registrant in place, the way `Map.set` does — for\n   *  registries where a second registration means \"newer version\", not\n   *  \"override\". Records no conflict. */\n  set(key: K, value: V, options?: RegisterOptions): void;\n  /** Drop every registrant of `key`. Returns whether there was one. */\n  delete(key: K): boolean;\n  clear(): void;\n  /** Announce a change the store cannot see — a registered value mutated in place. */\n  bump(): void;\n  /** This store as a {@link Reflection}, with no write methods on it. */\n  readonly reflection: Reflection<V, K>;\n}\n\n/**\n * Create a keyed store with a uniform reflection surface.\n *\n * Deliberately only the cross-cutting part of a registry: validation, lookup\n * fallbacks and lifecycle stay with the registry that embeds it.\n */\nexport function createReflectable<V, K = string>(): Reflectable<V, K> {\n  const stacks = new Map<K, Registrant<V>[]>();\n  const listeners = createEmitter();\n  let version = 0;\n  let snapshot: { version: number; entries: readonly ReflectedEntry<V, K>[] } | null = null;\n\n  function changed(): void {\n    version++;\n    listeners.emit();\n  }\n\n  const reflection: Reflection<V, K> = {\n    get: (key) => stacks.get(key)?.at(-1)?.value,\n    has: (key) => stacks.has(key),\n    entries() {\n      if (snapshot?.version === version) return snapshot.entries;\n      const entries: ReflectedEntry<V, K>[] = [];\n      for (const [key, stack] of stacks) {\n        const live = stack.at(-1)!;\n        entries.push(Object.freeze({\n          key, value: live.value, source: live.source, shadowed: Object.freeze(stack.slice(0, -1)),\n        }));\n      }\n      snapshot = { version, entries: Object.freeze(entries) };\n      return snapshot.entries;\n    },\n    subscribe: listeners.subscribe,\n    getVersion: () => version,\n  };\n\n  return {\n    ...reflection,\n    reflection,\n    push(key, value, options) {\n      const registrant: Registrant<V> = Object.freeze({ value, source: options?.source });\n      const stack = stacks.get(key);\n      if (stack) stack.push(registrant);\n      else stacks.set(key, [registrant]);\n      changed();\n      let released = false;\n      return () => {\n        if (released) return;\n        released = true;\n        const cur = stacks.get(key);\n        const i = cur ? cur.lastIndexOf(registrant) : -1;\n        if (i === -1) return;\n        cur!.splice(i, 1);\n        if (cur!.length === 0) stacks.delete(key);\n        changed();\n      };\n    },\n    set(key, value, options) {\n      const registrant: Registrant<V> = Object.freeze({ value, source: options?.source });\n      const stack = stacks.get(key);\n      if (stack) stack[stack.length - 1] = registrant;\n      else stacks.set(key, [registrant]);\n      changed();\n    },\n    delete(key) {\n      if (!stacks.delete(key)) return false;\n      changed();\n      return true;\n    },\n    clear() {\n      if (stacks.size === 0) return;\n      stacks.clear();\n      changed();\n    },\n    bump: changed,\n  };\n}\n","/** Whether `proto` is the prototype a plain object has: `null`, or some\n *  realm's `Object.prototype`. Comparing against this realm's alone misses\n *  objects made in an iframe, a VM context, or by `structuredClone` under jsdom. */\nexport function isPlainPrototype(proto: object | null): boolean {\n  return proto === Object.prototype || proto === null || Object.getPrototypeOf(proto) === null;\n}\n\n/** Whether `value` is a plain object — a literal or `Object.create(null)` — from any realm. */\nexport function isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && isPlainPrototype(Object.getPrototypeOf(value));\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/registry",
-  "version": "1.9.3",
+  "version": "1.9.4",
   "description": "Keyed registries with a uniform reflection surface: enumerate the entries, see which ones displaced others, subscribe to changes. No React, no DOM.",
   "license": "MIT",
   "type": "module",