@mmstack/primitives 22.8.2 → 22.8.4

package/package.json

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

package/types/mmstack-primitives.d.ts

@@ -1322,6 +1322,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).
  *
@@ -1335,11 +1357,15 @@ declare const mapArray: typeof indexArray;
  * when the list is reordered.
  *
  * @param source A `Signal<T[]>` or a function returning `T[]`.
- * @param mapFn The mapping function. Receives the item and its index as a Signal.
+ * @param mapFn The mapping function. Receives the item, its index as a Signal, and the
+ *   entry's key (the effective ordinal key when `duplicateKeys` is enabled, otherwise
+ *   the raw key) — stable for the lifetime of the mapped entry.
  * @param options Optional configuration:
  *  - `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
@@ -1363,7 +1389,7 @@ declare const mapArray: typeof indexArray;
  * users.set([users()[1], users()[0]]);
  * ```
  */
-declare function keyArray<T, U, K>(source: Signal<T[]> | (() => T[]), mapFn: (v: T, i: Signal<number>) => U, options?: {
+declare function keyArray<T, U, K>(source: Signal<T[]> | (() => T[]), mapFn: (v: T, i: Signal<number>, key: K | string) => U, options?: {
     onDestroy?: (value: U) => void;
     /**
      * Optional function to use a custom key for item comparison.
@@ -1371,6 +1397,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> = {
@@ -4493,4 +4525,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 };