@weasel-js/registry 1.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @weasel-js/registry
+
+Keyed registries with a uniform reflection surface: enumerate the entries, see which ones displaced others, subscribe to changes. No React, no DOM.
+
+Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
+scene-graph canvas kit for React. See the
+[API reference](https://orochi235.github.io/weasel/api/).
+
+## Install
+
+```sh
+npm install @weasel-js/registry
+```
+
+## Usage
+
+```ts
+import { /* … */ } from '@weasel-js/registry';
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/** One registrant of a key: its value and, when the registrant named one, where it came from. */
+interface Registrant<V> {
+    readonly value: V;
+    readonly source: string | undefined;
+}
+/** One key as a reflection reports it. */
+interface ReflectedEntry<V, K = string> extends Registrant<V> {
+    readonly key: K;
+    /** The registrants this one displaced, oldest first. Non-empty means two
+     *  registrants claimed one key — a conflict, resolved newest-wins. */
+    readonly shadowed: readonly Registrant<V>[];
+}
+/**
+ * The read-only face of a registry: what is registered, what displaced what,
+ * and a way to hear about changes. Every kit registry that embeds a
+ * {@link Reflectable} hands this out, so a debug overlay or a conflict check
+ * can walk any of them the same way.
+ *
+ * `subscribe` and `getVersion` are shaped for `useSyncExternalStore`; so is
+ * `entries`, which returns the same frozen array until the next change.
+ */
+interface Reflection<V, K = string> {
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    /** Every key's live registrant, in the order each key was first registered. */
+    entries(): readonly ReflectedEntry<V, K>[];
+    /** Called after every change. Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** Advances on every change. */
+    getVersion(): number;
+}
+/** Options for {@link Reflectable.push} and {@link Reflectable.set}. */
+interface RegisterOptions {
+    /** Who registered this — `'kit'`, a package, a plugin id. Reported, never interpreted. */
+    source?: string;
+}
+/**
+ * A keyed store that keeps its own {@link Reflection}. The registry owning it
+ * writes through `push` / `set` / `delete` and hands out `reflection`.
+ */
+interface Reflectable<V, K = string> extends Reflection<V, K> {
+    /** Register `value` over whatever `key` holds and return its release.
+     *  Registrants stack, newest live: releasing the live one uncovers the one
+     *  it displaced, and releasing a displaced one removes only it. Double-release safe. */
+    push(key: K, value: V, options?: RegisterOptions): () => void;
+    /** Replace `key`'s live registrant in place, the way `Map.set` does — for
+     *  registries where a second registration means "newer version", not
+     *  "override". Records no conflict. */
+    set(key: K, value: V, options?: RegisterOptions): void;
+    /** Drop every registrant of `key`. Returns whether there was one. */
+    delete(key: K): boolean;
+    clear(): void;
+    /** Announce a change the store cannot see — a registered value mutated in place. */
+    bump(): void;
+    /** This store as a {@link Reflection}, with no write methods on it. */
+    readonly reflection: Reflection<V, K>;
+}
+/**
+ * Create a keyed store with a uniform reflection surface.
+ *
+ * Deliberately only the cross-cutting part of a registry: validation, lookup
+ * fallbacks and lifecycle stay with the registry that embeds it.
+ */
+declare function createReflectable<V, K = string>(): Reflectable<V, K>;
+
+export { type Reflectable, type ReflectedEntry, type Reflection, type RegisterOptions, type Registrant, createReflectable };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/reflectable.ts
+function createReflectable() {
+  const stacks = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  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);
+      }
+    }
+  }
+  const reflection = {
+    get: (key) => stacks.get(key)?.at(-1)?.value,
+    has: (key) => stacks.has(key),
+    entries() {
+      if (snapshot?.version === version) return snapshot.entries;
+      const entries = [];
+      for (const [key, stack] of stacks) {
+        const live = stack.at(-1);
+        entries.push(Object.freeze({
+          key,
+          value: live.value,
+          source: live.source,
+          shadowed: Object.freeze(stack.slice(0, -1))
+        }));
+      }
+      snapshot = { version, entries: Object.freeze(entries) };
+      return snapshot.entries;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getVersion: () => version
+  };
+  return {
+    ...reflection,
+    reflection,
+    push(key, value, options) {
+      const registrant = Object.freeze({ value, source: options?.source });
+      const stack = stacks.get(key);
+      if (stack) stack.push(registrant);
+      else stacks.set(key, [registrant]);
+      changed();
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        const cur = stacks.get(key);
+        const i = cur ? cur.lastIndexOf(registrant) : -1;
+        if (i === -1) return;
+        cur.splice(i, 1);
+        if (cur.length === 0) stacks.delete(key);
+        changed();
+      };
+    },
+    set(key, value, options) {
+      const registrant = Object.freeze({ value, source: options?.source });
+      const stack = stacks.get(key);
+      if (stack) stack[stack.length - 1] = registrant;
+      else stacks.set(key, [registrant]);
+      changed();
+    },
+    delete(key) {
+      if (!stacks.delete(key)) return false;
+      changed();
+      return true;
+    },
+    clear() {
+      if (stacks.size === 0) return;
+      stacks.clear();
+      changed();
+    },
+    bump: changed
+  };
+}
+
+export { createReflectable };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@weasel-js/registry",
+  "version": "1.7.0",
+  "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",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "author": "orochi235",
+  "homepage": "https://orochi235.github.io/weasel/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orochi235/weasel.git",
+    "directory": "packages/registry"
+  },
+  "bugs": {
+    "url": "https://github.com/orochi235/weasel/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}