@mmstack/primitives 21.8.1 → 21.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "21.8.1",
+  "version": "21.8.3",
   "keywords": [
     "angular",
     "signals",

package/types/mmstack-primitives.d.ts

@@ -1315,6 +1315,28 @@ declare function indexArray<T, U>(source: Signal<T[]> | (() => T[]), map: (value
  */
 declare const mapArray: typeof indexArray;
 
+/**
+ * Opt-in policy describing how `keyArray` should treat duplicate keys.
+ *
+ * With the `'ordinal'` policy, keys are coerced to strings and disambiguated by
+ * their occurrence order: the first item with a given base key keeps `base`, the
+ * second becomes `base#1`, the third `base#2`, and so on. Each duplicate therefore
+ * gets a stable, distinct entry instead of collapsing.
+ *
+ * Identity follows position-among-duplicates: removing an earlier occurrence
+ * promotes the next one to the base key, which changes its effective key and thus
+ * re-creates its mapped entry.
+ */
+type DuplicateKeyPolicy = {
+    /** Disambiguation strategy. Currently only ordinal (`base`, `base#1`, `base#2`, ...). */
+    policy: 'ordinal';
+    /**
+     * Optional diagnostics side-channel. When a recompute observes duplicate keys,
+     * this is invoked once with the duplicate base keys in first-occurrence order.
+     * It is called untracked and must not be relied upon to create reactive dependencies.
+     */
+    report?: (bases: readonly string[]) => void;
+};
 /**
  * Reactively maps items from a source array to a new array by value (identity).
  *
@@ -1333,6 +1355,8 @@ declare const mapArray: typeof indexArray;
  *  - `onDestroy`: A callback invoked when a mapped item is removed from the array.
  *  - `key`: A custom key extractor for identity matching (e.g. `(item) => item.id`)
  *    when item references change but conceptual identity is preserved.
+ *  - `duplicateKeys`: Opt-in policy for handling duplicate keys. When omitted,
+ *    behavior is unchanged (duplicates collapse). See {@link DuplicateKeyPolicy}.
  * @returns A `Signal<U[]>` containing the mapped array.
  *
  * @example
@@ -1364,6 +1388,12 @@ declare function keyArray<T, U, K>(source: Signal<T[]> | (() => T[]), mapFn: (v:
      * even if the item reference changes.
      */
     key?: (item: T) => K;
+    /**
+     * Opt-in policy for disambiguating duplicate keys. When present, keys are
+     * coerced to strings and duplicates get distinct ordinal effective keys
+     * (`base`, `base#1`, `base#2`, ...). When absent, behavior is unchanged.
+     */
+    duplicateKeys?: DuplicateKeyPolicy;
 }): Signal<U[]>;
 
 type MappedObject<T extends object, U> = {
@@ -3094,10 +3124,14 @@ declare const STORE_SHARED_GLOBALS: unique symbol;
 type ProxyCache = WeakMap<object, Map<PropertyKey, WeakRef<Signal<any>>>>;
 /**
  * @internal
- * Prunes a cache entry once its proxy is reclaimed by the GC.
+ * Prunes a cache entry once its proxy is reclaimed by the GC. The held value must reference
+ * `target` only weakly: held values are retained by the registry until its cleanup callbacks
+ * run (host tasks — they never run inside a synchronous burst), so a strong `target` here
+ * keeps every dropped subtree's backing-signal ancestry alive across GCs. If `target` is
+ * already dead its whole cache entry died with it (WeakMap), and there is nothing to prune.
  */
 type ProxyCleanupRegistry = FinalizationRegistry<{
-    target: object;
+    targetRef: WeakRef<object>;
     prop: PropertyKey;
 }>;
 /**
@@ -4482,4 +4516,4 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
 export { CONCURRENCY_INSTRUMENTATION, MmActivity, MmTransition, MmViewTransitionName, OP_PROTO_VERSION, PAUSABLE_OPTIONS, PERSISTED_STORE_OPTIONS, POS_SEGMENT, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, applyOps, batteryStatus, bridgeScopeToPendingTasks, chunked, clipboard, combineWith, compareHlc, compareSiblings, compareTotal, createAttributedPending, createConvergingApply, createForwardingScope, createHlcClock, createStoreContext, createTransaction, createTransitionScope, debounce, debounced, defaultFold, deferredValue, derived, diffOps, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, insertElement, invertBatch, isConflicted, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, keyedArray, latest, lww, map, mapArray, mapObject, mediaQuery, merge3, mergeThree, mousePosition, moveElement, mutable, mutableStore, nestedEffect, networkStatus, opLog, opSync, opaque, orderedEntries, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, perfCustomTracks, persist, persistedStore, pipeable, piped, pointerDrag, policyStrategy, pooled, pooledArray, pooledMap, pooledSet, posBetween, prefersDarkMode, prefersReducedMotion, preserve, projection, provideConcurrencyInstrumentation, provideForwardingTransitionScope, providePausableOptions, providePaused, providePersistedStoreOptions, provideTransitionScope, rebalanceContainer, rebaseOps, reconcile, registerResource, removeElement, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, storeHistory, stored, syncedFork, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, use, validateEnvelope, windowSize, withHistory };
-export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ContainerNode, ConvergingApply, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, CreateTransitionScopeOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, Dot, DotFrontier, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, FoldFn, FoldPolicyEntry, FoldResult, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, Hlc, HlcClock, IdleOptions, IdleSignal, LatestSignal, MergeContext, MergeFn, MergePolicyEntry, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpEnvelope, OpLog, OpLogDriver, OpSync, OpSyncCheckpoint, OpSyncOptions, Opaque, OrderedEntry, PausableOptions, PauseOption, PersistHandle, PersistOptions, PersistedStore, PersistedStoreDefaults, PersistedStoreOptions, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, RebaseResult, ReconcileFn, ReconcileKey, RegisterCheckpoint, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreHistory, StoreHistoryOptions, StoreOp, StoreOptions, StoreTabSyncOptions, StoredSignal, SuspendType, SyncOp, SyncSibling, SyncSignalOptions, SyncedFork, TabSyncBus, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };
+export type { AsyncStore, BatteryStatus, ClipboardSignal, Computation, ConcurrencyInstrumentation, Conflicted, ContainerNode, ConvergingApply, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreateLatestOptions, CreateOpLogOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, CreateTransitionScopeOptions, DebouncedSignal, DeferStrategy, DeferredSignal, DeferredValueOptions, DerivedSignal, Dot, DotFrontier, DuplicateKeyPolicy, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, FoldFn, FoldPolicyEntry, FoldResult, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, Hlc, HlcClock, IdleOptions, IdleSignal, LatestSignal, MergeContext, MergeFn, MergePolicyEntry, MmTransitionContext, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, OpBatch, OpEnvelope, OpLog, OpLogDriver, OpSync, OpSyncCheckpoint, OpSyncOptions, Opaque, OrderedEntry, PausableOptions, PauseOption, PersistHandle, PersistOptions, PersistedStore, PersistedStoreDefaults, PersistedStoreOptions, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ProjectionOptions, RebaseResult, ReconcileFn, ReconcileKey, RegisterCheckpoint, RegisterOptions, ResourceLike, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreHistory, StoreHistoryOptions, StoreOp, StoreOptions, StoreTabSyncOptions, StoredSignal, SuspendType, SyncOp, SyncSibling, SyncSignalOptions, SyncedFork, TabSyncBus, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, UseSource, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };