@blac/core 2.1.0 → 2.1.2

package/dist/utils/idGenerator.d.ts

@@ -1,21 +1,14 @@
 /**
- * Centralized ID Generation
+ * Build an instance id: `${prefix}:${affix}` when an affix is given (the
+ * registry passes the instance key), otherwise `${prefix}:${timestamp}_${random}`.
  *
- * Provides consistent, collision-resistant ID generation for all BlaC subsystems.
- * Uses timestamp + counter + random suffix for uniqueness.
- */
-/**
- * Generate simple ID with timestamp and random (no counter tracking)
- *
- * Format: `${prefix}:${timestamp}_${random}`
- *
- * @param prefix - Prefix for the ID
- * @returns Branded ID string
+ * Ids are not unique: same-named classes share an id for the same affix, and
+ * the lazy `$blac.id` of an unregistered instance is always `${prefix}:main`.
  *
  * @example
  * ```ts
- * const id = generateSimpleId('CounterBloc');
- * // Returns: "CounterBloc:1698765432100_a3k9d7f2q"
+ * generateSimpleId('CounterBloc', 'default'); // "CounterBloc:default"
+ * generateSimpleId('CounterBloc'); // "CounterBloc:1698765432100_a3k9d7f2q"
  * ```
  */
 export declare function generateSimpleId(prefix: string, affix?: string): string;

package/dist/utils/static-props.d.ts

@@ -1,47 +1,46 @@
-/**
- * Utility functions for accessing static properties on StateContainer classes
- */
 import type { EqualityFn } from '../config';
 import { StateContainerConstructor } from '../types/utilities';
 /**
- * Get a static property from a class constructor
- * Type-safe helper that avoids (Type as any) casts
- *
- * @param Type - The class constructor
- * @param propName - The property name to access
- * @param defaultValue - Optional default value if property is undefined
- * @returns The property value or default
+ * Get a static property from a class constructor, walking the prototype
+ * chain so subclasses inherit the value unless they define their own.
  */
-export declare function getStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string, defaultValue?: V): V | undefined;
+export declare function getStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string): V | undefined;
 /**
- * Check if a class is marked as keepAlive.
- * KeepAlive classes are never auto-disposed when ref count reaches 0.
- * @param Type - The class constructor to check
- * @returns true if the class has `static keepAlive = true`
+ * Get a static property declared directly on `Type`, ignoring the prototype
+ * chain, so subclasses never inherit a base class's value.
+ */
+export declare function getOwnStaticProp<V, T extends StateContainerConstructor = StateContainerConstructor>(Type: T, propName: string): V | undefined;
+/**
+ * Whether a class is marked `keepAlive` (never auto-disposed at ref count 0).
+ * Inherited: a subclass keeps a base class's `keepAlive` unless overridden.
  */
 export declare function isKeepAliveClass<T extends StateContainerConstructor>(Type: T): boolean;
 /**
- * Check if a class should be excluded from DevTools.
- * Used to prevent infinite loops when DevTools tracks itself.
- * @param Type - The class constructor to check
- * @returns true if the class has `static __excludeFromDevTools = true`
+ * Whether a class is marked `isolated` (each `useBloc` mount gets its own
+ * instance). Inherited: a subclass keeps a base class's `isolated` unless
+ * overridden.
+ */
+export declare function isIsolatedClass<T extends StateContainerConstructor>(Type: T): boolean;
+/**
+ * Whether a class is excluded from DevTools (avoids DevTools tracking itself
+ * into an infinite loop). Inherited unless overridden by a subclass.
  */
 export declare function isExcludedFromDevTools<T extends StateContainerConstructor>(Type: T): boolean;
 /**
  * Get the per-class equality function set via `@blac({ equality })`, if any.
- * @param Type - The class constructor to check
- * @returns the equality function or `undefined`
+ * Inherited: a subclass keeps a base class's equality fn unless overridden.
  */
 export declare function getClassEquality<T extends StateContainerConstructor>(Type: T): EqualityFn | undefined;
 /**
- * Get the per-class key function set via `@blac({ key })` or `static key = …`, if any.
- * Used by the registry to derive a stable instance key from `args`.
- * @param Type - The class constructor to check
- * @returns the key function or `undefined`
+ * Get a class's minification-safe identity name (`static blacName`), falling
+ * back to `Type.name`. Own only: a subclass never inherits a base class's
+ * explicit `blacName`, since that would collapse two distinct blocs onto one
+ * identity.
  */
-export declare function getClassKey(Type: unknown): ((args: any) => string) | undefined;
+export declare function getBlacName<T extends StateContainerConstructor>(Type: T): string;
 /**
- * Check if a class is marked as always-per-mount.
- * @returns true if the class has `static isolated = true`
+ * Get the per-class key function set via `@blac({ key })` or `static key = …`.
+ * Own only: a subclass never inherits a base class's `key`, since a
+ * different `Args` shape would derive the wrong instance key.
  */
-export declare function isIsolatedClass<T extends StateContainerConstructor>(Type: T): boolean;
+export declare function getClassKey(Type: unknown): ((args: any) => string) | undefined;

package/dist/utils/structural-key.d.ts

@@ -1,24 +1,2 @@
-/**
- * Deterministic, order-independent hash of serializable args.
- * Sorts object keys so {a,b} === {b,a}.
- *
- * - Functions throw a friendly `[blac]` error — they must be passed via `deps`.
- * - `Date` (and anything else with a `toJSON`) serializes via that `toJSON`
- *   (e.g. as an ISO string), since `JSON.stringify` calls it before the
- *   replacer ever sees the value — there's no cheap way to guard against
- *   non-plain objects here.
- * - `BigInt` and circular args throw `JSON.stringify`'s own raw `TypeError`,
- *   not the friendly `[blac]` message.
- * - `undefined` values inside objects are preserved via a reserved sentinel
- *   (rather than being dropped, which is `JSON.stringify`'s default and would
- *   let structurally different args collide on the same key).
- */
 export declare const DEFAULT_STRUCTURAL_KEY = "default";
-/**
- * Produce a stable string key for serializable args.
- * - `undefined` / `void` args → `'default'` sentinel (no-args blocs stay on the default key).
- * - Object keys are sorted for order-independence.
- * - Arrays keep their insertion order.
- * - Functions throw — they must be passed via `deps`, not `args`.
- */
 export declare function structuralKey(args: unknown): string;

package/dist/watch/index.d.ts

@@ -1,3 +1,2 @@
 export { watch, instance } from './watch';
-export type { WatchFn, BlocRef } from './watch';
-export { observe } from './observe';
+export type { WatchFn, WatchOptions, BlocRef } from './watch';

package/dist/watch/watch.d.ts

@@ -31,6 +31,26 @@ export interface BlocRef<T extends StateContainerConstructor> {
  */
 export declare function instance<T extends StateContainerConstructor>(BlocClass: T, args?: ExtractArgs<T>): BlocRef<T>;
 type BlocInput = StateContainerConstructor | BlocRef<StateContainerConstructor>;
+/**
+ * Options for `watch`.
+ */
+export interface WatchOptions {
+    /**
+     * When `false`, `watch` observes passively: it neither creates a missing
+     * instance nor takes a real ownership ref on an existing one. If the
+     * instance does not exist yet, the callback simply never fires — `watch`
+     * does not poll; call it again once the instance exists.
+     *
+     * Defaults to `true`.
+     */
+    create?: boolean;
+    /**
+     * Stops the watch when aborted, equivalent to calling the returned stop
+     * function. An already-aborted signal returns a no-op stop without
+     * creating or acquiring anything.
+     */
+    signal?: AbortSignal;
+}
 type ExtractInstance<T> = T extends BlocRef<infer C> ? InstanceType<C> : T extends StateContainerConstructor ? InstanceType<T> : never;
 type ExtractInstances<T extends readonly BlocInput[]> = {
     [K in keyof T]: ExtractInstance<T[K]>;
@@ -39,21 +59,21 @@ type ExtractInstances<T extends readonly BlocInput[]> = {
  * Watch function signature for single bloc.
  */
 export interface WatchSingleFn {
-    <T extends StateContainerConstructor>(bloc: T | BlocRef<T>, callback: (bloc: InstanceType<T>) => void | StopSymbol): () => void;
+    <T extends StateContainerConstructor>(bloc: T | BlocRef<T>, callback: (bloc: InstanceType<T>) => void | StopSymbol, options?: WatchOptions): () => void;
     STOP: StopSymbol;
 }
 /**
  * Watch function signature for multiple blocs.
  */
 export interface WatchMultipleFn {
-    <T extends readonly BlocInput[]>(blocs: T, callback: (blocs: ExtractInstances<T>) => void | StopSymbol): () => void;
+    <T extends readonly BlocInput[]>(blocs: T, callback: (blocs: ExtractInstances<T>) => void | StopSymbol, options?: WatchOptions): () => void;
     STOP: StopSymbol;
 }
 /**
  * Combined watch function type.
  */
 export interface WatchFn extends WatchSingleFn {
-    <T extends readonly BlocInput[]>(blocs: T, callback: (blocs: ExtractInstances<T>) => void | StopSymbol): () => void;
+    <T extends readonly BlocInput[]>(blocs: T, callback: (blocs: ExtractInstances<T>) => void | StopSymbol, options?: WatchOptions): () => void;
 }
 export declare const watch: WatchFn;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blac/core",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "license": "MIT",
   "author": "Brendan Mullins <jsnanigans@gmail.com>",
   "description": "Type-safe, class-based state management with proxy tracking and plugin system",
@@ -22,17 +22,11 @@
       "testing": [
         "./dist/testing.d.ts"
       ],
-      "debug": [
-        "./dist/debug.d.ts"
-      ],
       "plugins": [
         "./dist/plugins.d.ts"
       ],
-      "watch": [
-        "./dist/watch-entry.d.ts"
-      ],
-      "types": [
-        "./dist/types.d.ts"
+      "internal": [
+        "./dist/internal.d.ts"
       ]
     }
   },
@@ -47,16 +41,6 @@
         "default": "./dist/index.cjs"
       }
     },
-    "./debug": {
-      "import": {
-        "types": "./dist/debug.d.ts",
-        "default": "./dist/debug.js"
-      },
-      "require": {
-        "types": "./dist/debug.d.cts",
-        "default": "./dist/debug.cjs"
-      }
-    },
     "./plugins": {
       "import": {
         "types": "./dist/plugins.d.ts",
@@ -67,26 +51,6 @@
         "default": "./dist/plugins.cjs"
       }
     },
-    "./watch": {
-      "import": {
-        "types": "./dist/watch-entry.d.ts",
-        "default": "./dist/watch-entry.js"
-      },
-      "require": {
-        "types": "./dist/watch-entry.d.cts",
-        "default": "./dist/watch-entry.cjs"
-      }
-    },
-    "./types": {
-      "import": {
-        "types": "./dist/types.d.ts",
-        "default": "./dist/types.js"
-      },
-      "require": {
-        "types": "./dist/types.d.cts",
-        "default": "./dist/types.cjs"
-      }
-    },
     "./testing": {
       "import": {
         "types": "./dist/testing.d.ts",
@@ -96,6 +60,16 @@
         "types": "./dist/testing.d.cts",
         "default": "./dist/testing.cjs"
       }
+    },
+    "./internal": {
+      "import": {
+        "types": "./dist/internal.d.ts",
+        "default": "./dist/internal.js"
+      },
+      "require": {
+        "types": "./dist/internal.d.cts",
+        "default": "./dist/internal.cjs"
+      }
     }
   },
   "files": [
@@ -118,27 +92,26 @@
     {
       "name": "@blac/core (ESM, brotli)",
       "path": "dist/index.js",
-      "limit": "9.2 kB"
+      "limit": "15 kB"
     }
   ],
   "dependencies": {
-    "@dirtytalk/structural": "^0.0.9"
+    "@dirtytalk/structural": "^0.1.4"
   },
   "devDependencies": {
-    "@size-limit/preset-small-lib": "^11.1.6",
-    "size-limit": "^11.1.6",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/user-event": "^14.6.1",
-    "@types/node": "^25.9.1",
-    "arktype": "^2.2.0",
-    "fast-check": "^4.8.0",
-    "jsdom": "^29.1.1",
-    "publint": "^0.3.21",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/user-event": "^14.6.7",
+    "@types/node": "^26.4.1",
+    "arktype": "^2.2.3",
+    "fast-check": "^4.9.0",
+    "publint": "^0.3.24",
+    "size-limit": "^13.0.3",
     "typescript": "^6.0.3",
-    "valibot": "^1.4.1",
-    "vite-plus": "^0.1.23",
-    "vitest": "npm:@voidzero-dev/vite-plus-test@latest",
-    "zod": "^4.4.3"
+    "valibot": "^1.4.2",
+    "vite-plus": "^0.1.24",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.24",
+    "zod": "^4.5.4"
   },
   "scripts": {
     "dev": "vp pack --watch",
@@ -153,6 +126,7 @@
     "coverage": "vp test run --coverage",
     "verify": "node ../../scripts/run-workspace-bin.mjs publint",
     "typecheck": "tsc --noEmit",
+    "api:check": "for f in api-extractor.*.json; do api-extractor run -c \"$f\" || exit 1; done",
     "size": "size-limit",
     "deploy": "pnpm publish --access public"
   }