signalkin 0.2.0

package/fesm2022/signalkin.mjs

@@ -0,0 +1,598 @@
+import { computed } from '@angular/core';
+import { signalStoreFeature, withComputed, withMethods, patchState, withState } from '@ngrx/signals';
+import { addEntity, addEntities, prependEntity, prependEntities, setEntity, setEntities, setAllEntities, upsertEntity, upsertEntities, updateEntity, updateEntities, updateAllEntities, removeEntity, removeEntities, removeAllEntities } from '@ngrx/signals/entities';
+
+const capitalize = (value) => value.charAt(0).toUpperCase() + value.slice(1);
+const addUnique = (list, id) => list?.includes(id) ? list : [...(list ?? []), id];
+/** Whether an accessor returned a usable id (keeps `0` and `''`, drops `undefined` / `null`). */
+const hasId = (id) => id !== undefined && id !== null;
+/** Turns a primary-id key-or-getter accessor into a getter; a string is read as a property name off the entity. */
+const toIdReader = (accessor, defaultKey) => {
+    const resolved = accessor ?? defaultKey;
+    return typeof resolved === 'function' ? resolved : (entity) => entity?.[resolved];
+};
+/**
+ * Resolves a lookup argument that may be an entity OR its id down to the id: an object is read
+ * through `readId`, anything else (a raw id) passes through. Lets every lookup accept `Entity | EntityId`.
+ */
+const toRefResolver = (readId) => (ref) => ref !== null && typeof ref === 'object' ? readId(ref) : ref;
+/**
+ * A foreign-key reader that always yields an array of usable ids: a scalar id becomes a one-item
+ * array, an array (a plural FK like `aisleIds`) passes through, and a missing/empty key yields `[]`.
+ * This lets a `>1` side carry an array foreign key without the caller normalizing.
+ */
+const toIdsReader = (accessor, defaultKey) => {
+    const read = typeof accessor === 'function' ? accessor : (entity) => entity?.[accessor ?? defaultKey];
+    return (entity) => {
+        const value = read(entity);
+        return Array.isArray(value) ? value.filter(hasId) : hasId(value) ? [value] : [];
+    };
+};
+/** Unions two adjacency maps, deduping ids per key. */
+const mergeLinks = (base, extra) => {
+    const merged = {};
+    [base, extra].forEach((source) => Object.keys(source).forEach((keyId) => {
+        merged[keyId] = source[keyId].reduce((ids, id) => addUnique(ids, id), merged[keyId] ?? []);
+    }));
+    return merged;
+};
+/**
+ * Drops links whose source or target entity no longer exists, so lookups never
+ * return ids for entities that were removed from their collection.
+ */
+const projectLinks = (links, keyEntityMap, valueEntityMap) => {
+    const projected = {};
+    Object.keys(links).forEach((keyId) => {
+        if (keyEntityMap[keyId] === undefined)
+            return;
+        projected[keyId] = links[keyId].filter((valueId) => valueEntityMap[valueId] !== undefined);
+    });
+    return projected;
+};
+
+/**
+ * Standard collection methods and convenience signals for the store's entities, named by collection — no args covers every collection, or pass configs to narrow and to honor a custom `selectId` / `plural`.
+ *
+ * @example
+ * signalStore(
+ *   withEntities(bookConfig),
+ *   withEntityAccessors(bookConfig),
+ * );
+ * // books(), bookMap(), bookCount(), bookById(id), hasBook(book | id)
+ * // addBook, addBooks, prependBook, setBook, setAllBooks, upsertBook
+ * // updateBook(book | id, changes), updateAllBooks(changes), removeBook(book | id), removeAllBooks()
+ * // swapBooks(a, b), reorderBooks(orderedBooks), moveBookToIndex(book | id, index) reorder the collection
+ */
+const withEntityAccessors = (...configs) => {
+    const resolveCollections = (innerStore) => configs.length > 0
+        ? configs.map((config) => {
+            if (typeof innerStore[`${config.collection}EntityMap`] !== 'function') {
+                throw new Error(`signalkin: '${config.collection}EntityMap' is not on the store — register withEntities ` +
+                    `for '${config.collection}' before withEntityAccessors.`);
+            }
+            return config.collection;
+        })
+        : Object.keys(innerStore)
+            .filter((key) => key.endsWith('EntityMap') && key !== 'EntityMap')
+            .map((key) => key.slice(0, -'EntityMap'.length));
+    const selectIdFor = (collection) => configs.find((config) => config.collection === collection)?.selectId;
+    const pluralFor = (collection) => configs.find((config) => config.collection === collection)?.plural ?? `${collection}s`;
+    const feature = signalStoreFeature(withComputed((innerStore) => {
+        const props = {};
+        resolveCollections(innerStore).forEach((collection) => {
+            props[pluralFor(collection)] = computed(() => innerStore[`${collection}Entities`]());
+            props[`${collection}Map`] = computed(() => innerStore[`${collection}EntityMap`]());
+            props[`${collection}Count`] = computed(() => innerStore[`${collection}Ids`]().length);
+        });
+        return props;
+    }), withMethods((innerStore) => {
+        const methods = {};
+        resolveCollections(innerStore).forEach((collection) => {
+            const capitalizedCollection = capitalize(collection);
+            const capitalizedPlural = capitalize(pluralFor(collection));
+            const entityMapKey = `${collection}EntityMap`;
+            const updaterConfig = { collection, selectId: selectIdFor(collection) };
+            const resolveRef = toRefResolver(toIdReader(selectIdFor(collection), 'id'));
+            const resolveTargets = (entitiesOrPredicate) => Array.isArray(entitiesOrPredicate) ? entitiesOrPredicate.map(resolveRef) : entitiesOrPredicate;
+            methods[`add${capitalizedCollection}`] = (entity) => patchState(innerStore, addEntity(entity, updaterConfig));
+            methods[`add${capitalizedPlural}`] = (entities) => patchState(innerStore, addEntities(entities, updaterConfig));
+            methods[`prepend${capitalizedCollection}`] = (entity) => patchState(innerStore, prependEntity(entity, updaterConfig));
+            methods[`prepend${capitalizedPlural}`] = (entities) => patchState(innerStore, prependEntities(entities, updaterConfig));
+            methods[`set${capitalizedCollection}`] = (entity) => patchState(innerStore, setEntity(entity, updaterConfig));
+            methods[`set${capitalizedPlural}`] = (entities) => patchState(innerStore, setEntities(entities, updaterConfig));
+            methods[`setAll${capitalizedPlural}`] = (entities) => patchState(innerStore, setAllEntities(entities, updaterConfig));
+            methods[`upsert${capitalizedCollection}`] = (entity) => patchState(innerStore, upsertEntity(entity, updaterConfig));
+            methods[`upsert${capitalizedPlural}`] = (entities) => patchState(innerStore, upsertEntities(entities, updaterConfig));
+            methods[`update${capitalizedCollection}`] = (ref, changes) => patchState(innerStore, updateEntity({ id: resolveRef(ref), changes }, updaterConfig));
+            methods[`update${capitalizedPlural}`] = (entitiesOrPredicate, changes) => patchState(innerStore, updateEntities((Array.isArray(entitiesOrPredicate)
+                ? { ids: resolveTargets(entitiesOrPredicate), changes }
+                : { predicate: entitiesOrPredicate, changes }), updaterConfig));
+            methods[`updateAll${capitalizedPlural}`] = (changes) => patchState(innerStore, updateAllEntities(changes, updaterConfig));
+            methods[`remove${capitalizedCollection}`] = (ref) => patchState(innerStore, removeEntity(resolveRef(ref), updaterConfig));
+            methods[`remove${capitalizedPlural}`] = (entitiesOrPredicate) => patchState(innerStore, removeEntities(resolveTargets(entitiesOrPredicate), updaterConfig));
+            methods[`removeAll${capitalizedPlural}`] = () => patchState(innerStore, removeAllEntities(updaterConfig));
+            // Ordering mutations over the collection's own id order (what `${collection}Entities` follows).
+            const idsKey = `${collection}Ids`;
+            const writeIds = (ids) => patchState(innerStore, { [idsKey]: ids });
+            methods[`swap${capitalizedPlural}`] = (aRef, bRef) => {
+                const ids = [...innerStore[idsKey]()];
+                const indexA = ids.indexOf(resolveRef(aRef));
+                const indexB = ids.indexOf(resolveRef(bRef));
+                if (indexA === -1 || indexB === -1) {
+                    console.warn(`signalkin: swap${capitalizedPlural} — both entities must be in the '${collection}' collection; call ignored.`);
+                    return;
+                }
+                [ids[indexA], ids[indexB]] = [ids[indexB], ids[indexA]];
+                writeIds(ids);
+            };
+            methods[`reorder${capitalizedPlural}`] = (orderedEntities) => {
+                const orderedIds = (orderedEntities ?? []).map(resolveRef).filter((id) => id !== undefined);
+                const current = innerStore[idsKey]();
+                const isFullPermutation = orderedIds.length === current.length &&
+                    new Set(orderedIds).size === orderedIds.length &&
+                    orderedIds.every((id) => current.includes(id));
+                if (!isFullPermutation) {
+                    console.warn(`signalkin: reorder${capitalizedPlural} — pass every '${collection}' entity exactly once; call ignored.`);
+                    return;
+                }
+                writeIds(orderedIds);
+            };
+            methods[`move${capitalizedCollection}ToIndex`] = (ref, index) => {
+                const ids = [...innerStore[idsKey]()];
+                const currentIndex = ids.indexOf(resolveRef(ref));
+                if (currentIndex === -1)
+                    return;
+                const target = Math.max(0, Math.min(index, ids.length - 1));
+                const [moved] = ids.splice(currentIndex, 1);
+                ids.splice(target, 0, moved);
+                writeIds(ids);
+            };
+            methods[`${collection}ById`] = (id) => innerStore[entityMapKey]()[id];
+            methods[`has${capitalizedCollection}`] = (ref) => innerStore[entityMapKey]()[resolveRef(ref)] !== undefined;
+        });
+        return methods;
+    }));
+    return feature;
+};
+
+/**
+ * Relates two entity collections into typed cross-lookups, counts, composite set-lookups, and link mutations named by each side's `collection`; `count` (`1`, a number, or `'many'`) drives the names and shapes, and every lookup takes the entity or its id.
+ *
+ * @example
+ * signalStore(
+ *   withEntities(libraryConfig),
+ *   withEntities(bookConfig),
+ *   withEntityRelationship({ collection: 'library', count: 1 }, { collection: 'book', count: 'many' }),
+ * );
+ * // booksByLibrary(library | id) -> Book[]
+ * // libraryByBook(book | id) -> Library | undefined
+ * // libraryHasBook, bookCountByLibrary, addBookToLibrary, removeBookFromLibrary, moveBookToLibrary
+ * // indexOfLibraryBook(book | id) -> number (the book's position in its library, -1 if absent)
+ * // swapLibraryBooks(a, b), reorderLibraryBooks(orderedBooks), moveLibraryBookToIndex(book, index) reorder a library's books
+ * // book side is 'many', so a set-lookup keyed by a full book-set: libraryByBooks(...books | ids) -> Library
+ */
+const withEntityRelationship = (from, to, options) => {
+    const fromName = from.collection;
+    const toName = to.collection;
+    const fromPlural = from.plural ?? `${fromName}s`;
+    const toPlural = to.plural ?? `${toName}s`;
+    const fromIsSingle = from.count === 1;
+    const toIsSingle = to.count === 1;
+    const autoIndex = options?.autoIndex ?? true;
+    const syncForeignKeys = options?.syncForeignKeys ?? true;
+    const compositeLookups = options?.compositeLookups ?? true;
+    const readFromPrimaryId = toIdReader(from.selectId, 'id');
+    const readToPrimaryId = toIdReader(to.selectId, 'id');
+    // Default foreign-key name pluralizes when the side points at MORE THAN ONE of the other.
+    const fromForeignKeyDefault = toIsSingle ? `${toName}Id` : `${toName}Ids`;
+    const toForeignKeyDefault = fromIsSingle ? `${fromName}Id` : `${fromName}Ids`;
+    const readFromForeignIds = toIdsReader(from.selectForeignId, fromForeignKeyDefault);
+    const readToForeignIds = toIdsReader(to.selectForeignId, toForeignKeyDefault);
+    // The WRITABLE foreign-key property per side, for syncForeignKeys — undefined when the accessor is
+    // a getter, which can't be written back.
+    const fromForeignKey = typeof from.selectForeignId === 'function' ? undefined : (from.selectForeignId ?? fromForeignKeyDefault);
+    const toForeignKey = typeof to.selectForeignId === 'function' ? undefined : (to.selectForeignId ?? toForeignKeyDefault);
+    const forwardLinksKey = `_${fromName}${capitalize(toName)}Links`;
+    const reverseLinksKey = `_${toName}${capitalize(fromName)}Links`;
+    const forwardMapKey = `${fromName}${capitalize(toName)}Map`;
+    const reverseMapKey = `${toName}${capitalize(fromName)}Map`;
+    const fromEntityMapKey = `${fromName}EntityMap`;
+    const toEntityMapKey = `${toName}EntityMap`;
+    const feature = signalStoreFeature(withState(() => ({
+        [forwardLinksKey]: {},
+        [reverseLinksKey]: {},
+    })), withComputed((innerStore) => {
+        // Links derived from each side's foreign key, rebuilt whenever either collection changes.
+        const foreignLinks = computed(() => {
+            const forward = {};
+            const backward = {};
+            if (!autoIndex)
+                return { forward, backward };
+            // A to-side entity naming its from-side owner(s) (e.g. book.libraryId, or a book's aisleIds).
+            Object.values(innerStore[toEntityMapKey]()).forEach((entity) => {
+                const toId = readToPrimaryId(entity);
+                if (!hasId(toId))
+                    return;
+                readToForeignIds(entity).forEach((fromId) => {
+                    forward[fromId] = addUnique(forward[fromId], toId);
+                    backward[toId] = addUnique(backward[toId], fromId);
+                });
+            });
+            // A from-side entity naming its to-side(s) (covers the reverse direction and m:n).
+            Object.values(innerStore[fromEntityMapKey]()).forEach((entity) => {
+                const fromId = readFromPrimaryId(entity);
+                if (!hasId(fromId))
+                    return;
+                readFromForeignIds(entity).forEach((toId) => {
+                    forward[fromId] = addUnique(forward[fromId], toId);
+                    backward[toId] = addUnique(backward[toId], fromId);
+                });
+            });
+            return { forward, backward };
+        }, /* @ts-ignore */
+        ...(ngDevMode ? [{ debugName: "foreignLinks" }] : /* istanbul ignore next */ []));
+        return {
+            [forwardMapKey]: computed(() => projectLinks(mergeLinks(innerStore[forwardLinksKey](), foreignLinks().forward), innerStore[fromEntityMapKey](), innerStore[toEntityMapKey]())),
+            [reverseMapKey]: computed(() => projectLinks(mergeLinks(innerStore[reverseLinksKey](), foreignLinks().backward), innerStore[toEntityMapKey](), innerStore[fromEntityMapKey]())),
+        };
+    }), withMethods((innerStore) => {
+        const resolveFromRef = toRefResolver(readFromPrimaryId);
+        const resolveToRef = toRefResolver(readToPrimaryId);
+        const resolveEntities = (ids, entityMapKey) => (ids ?? []).map((id) => innerStore[entityMapKey]()[id]).filter((entity) => entity !== undefined);
+        const writeLinks = (forward, backward) => patchState(innerStore, { [forwardLinksKey]: forward, [reverseLinksKey]: backward });
+        const addLink = (fromId, toId) => {
+            const forward = { ...innerStore[forwardLinksKey]() };
+            const backward = { ...innerStore[reverseLinksKey]() };
+            forward[fromId] = addUnique(forward[fromId], toId);
+            backward[toId] = addUnique(backward[toId], fromId);
+            writeLinks(forward, backward);
+        };
+        const fromUpdaterConfig = { collection: fromName, selectId: (entity) => readFromPrimaryId(entity) };
+        const toUpdaterConfig = { collection: toName, selectId: (entity) => readToPrimaryId(entity) };
+        /**
+         * Writes one entity's foreign key when syncForeignKeys is on and the side has a writable key:
+         * the current FK ids run through `mutate`, then an array FK is replaced with the result and a
+         * scalar FK with its first id (`undefined` clears it). No-ops on a missing entity or unchanged result.
+         */
+        const writeForeignIds = (entityMapKey, updaterConfig, foreignKey, isArrayForeignKey, entityId, mutate) => {
+            if (!syncForeignKeys || foreignKey === undefined)
+                return;
+            const entity = innerStore[entityMapKey]()[entityId];
+            if (entity === undefined)
+                return;
+            const current = entity[foreignKey];
+            const currentIds = Array.isArray(current) ? current.filter(hasId) : hasId(current) ? [current] : [];
+            const nextIds = mutate(currentIds);
+            if (nextIds.length === currentIds.length && nextIds.every((id, index) => id === currentIds[index]))
+                return;
+            const nextValue = isArrayForeignKey ? nextIds : nextIds[0];
+            patchState(innerStore, updateEntity({ id: entityId, changes: { [foreignKey]: nextValue } }, updaterConfig));
+        };
+        /**
+         * Persists an owner's reordered member list into the owner's OWN array foreign key (e.g.
+         * `cell.optionIds`), so a swap/reorder/move survives in the entity, not just the manual link. Gated
+         * by syncForeignKeys, and only when the owner actually stores that key as an array — a 1:many owner
+         * keeps order through its members' back-references, so there is nothing to write and we never
+         * fabricate a key on a side that doesn't hold one.
+         */
+        const writeOwnerForeignOrder = (entityMapKey, updaterConfig, foreignKey, ownerId, orderedIds) => {
+            if (!syncForeignKeys || foreignKey === undefined)
+                return;
+            const owner = innerStore[entityMapKey]()[ownerId];
+            if (!owner || !Array.isArray(owner[foreignKey]))
+                return;
+            writeForeignIds(entityMapKey, updaterConfig, foreignKey, true, ownerId, () => orderedIds);
+        };
+        const writeFromOwnerOrder = (ownerId, orderedIds) => writeOwnerForeignOrder(fromEntityMapKey, fromUpdaterConfig, fromForeignKey, ownerId, orderedIds);
+        const writeToOwnerOrder = (ownerId, orderedIds) => writeOwnerForeignOrder(toEntityMapKey, toUpdaterConfig, toForeignKey, ownerId, orderedIds);
+        // Removes the manual link, and (with syncForeignKeys) also clears the matching id from both
+        // entities' foreign keys — otherwise an FK-derived link regenerates on the next read.
+        const removeLink = (fromId, toId) => {
+            const forward = { ...innerStore[forwardLinksKey]() };
+            const backward = { ...innerStore[reverseLinksKey]() };
+            forward[fromId] = (forward[fromId] ?? []).filter((id) => id !== toId);
+            backward[toId] = (backward[toId] ?? []).filter((id) => id !== fromId);
+            writeLinks(forward, backward);
+            writeForeignIds(toEntityMapKey, toUpdaterConfig, toForeignKey, !fromIsSingle, toId, (ids) => ids.filter((id) => id !== fromId));
+            writeForeignIds(fromEntityMapKey, fromUpdaterConfig, fromForeignKey, !toIsSingle, fromId, (ids) => ids.filter((id) => id !== toId));
+        };
+        const moveTo = (toId, newFromId) => {
+            const forward = { ...innerStore[forwardLinksKey]() };
+            const backward = { ...innerStore[reverseLinksKey]() };
+            (backward[toId] ?? []).forEach((fromId) => {
+                forward[fromId] = (forward[fromId] ?? []).filter((id) => id !== toId);
+            });
+            backward[toId] = [newFromId];
+            forward[newFromId] = addUnique(forward[newFromId], toId);
+            writeLinks(forward, backward);
+            // With syncForeignKeys: re-point the to-entity's FK, and move the to-id from every old
+            // from-entity's FK to the new one.
+            writeForeignIds(toEntityMapKey, toUpdaterConfig, toForeignKey, !fromIsSingle, toId, () => [newFromId]);
+            if (syncForeignKeys && fromForeignKey !== undefined) {
+                Object.values(innerStore[fromEntityMapKey]()).forEach((entity) => {
+                    const fromId = readFromPrimaryId(entity);
+                    if (!hasId(fromId) || fromId === newFromId)
+                        return;
+                    writeForeignIds(fromEntityMapKey, fromUpdaterConfig, fromForeignKey, !toIsSingle, fromId, (ids) => ids.filter((id) => id !== toId));
+                });
+                writeForeignIds(fromEntityMapKey, fromUpdaterConfig, fromForeignKey, !toIsSingle, newFromId, (ids) => addUnique(ids, toId));
+            }
+        };
+        const toEntityLead = toIsSingle ? toName : toPlural;
+        const toIdLead = toIsSingle ? `${toName}Id` : `${toName}Ids`;
+        const fromEntityLead = fromIsSingle ? fromName : fromPlural;
+        const fromIdLead = fromIsSingle ? `${fromName}Id` : `${fromName}Ids`;
+        const capitalizedFrom = capitalize(fromName);
+        const capitalizedTo = capitalize(toName);
+        const toIdsByFrom = (fromId) => hasId(fromId) ? innerStore[forwardMapKey]()[fromId] ?? [] : [];
+        const fromIdsByTo = (toId) => hasId(toId) ? innerStore[reverseMapKey]()[toId] ?? [] : [];
+        // The adjacency maps are already pruned (projectLinks), so their ids resolve to live entities.
+        const shapeToEntities = (ids) => toIsSingle ? resolveEntities(ids, toEntityMapKey)[0] : resolveEntities(ids, toEntityMapKey);
+        const shapeFromEntities = (ids) => fromIsSingle ? resolveEntities(ids, fromEntityMapKey)[0] : resolveEntities(ids, fromEntityMapKey);
+        const shapeToIds = (ids) => (toIsSingle ? ids[0] : ids);
+        const shapeFromIds = (ids) => (fromIsSingle ? ids[0] : ids);
+        const methods = {
+            [`${toEntityLead}By${capitalizedFrom}`]: (from) => shapeToEntities(toIdsByFrom(resolveFromRef(from))),
+            [`${toIdLead}By${capitalizedFrom}`]: (from) => shapeToIds(toIdsByFrom(resolveFromRef(from))),
+            [`${fromEntityLead}By${capitalizedTo}`]: (to) => shapeFromEntities(fromIdsByTo(resolveToRef(to))),
+            [`${fromIdLead}By${capitalizedTo}`]: (to) => shapeFromIds(fromIdsByTo(resolveToRef(to))),
+            [`${fromName}Has${capitalizedTo}`]: (from, to) => (innerStore[forwardMapKey]()[resolveFromRef(from)] ?? []).includes(resolveToRef(to)),
+            [`${toName}Has${capitalizedFrom}`]: (to, from) => (innerStore[reverseMapKey]()[resolveToRef(to)] ?? []).includes(resolveFromRef(from)),
+            [`${toName}CountBy${capitalizedFrom}`]: (from) => (innerStore[forwardMapKey]()[resolveFromRef(from)] ?? []).length,
+            [`${fromName}CountBy${capitalizedTo}`]: (to) => (innerStore[reverseMapKey]()[resolveToRef(to)] ?? []).length,
+            [`add${capitalizedTo}To${capitalizedFrom}`]: (from, to) => addLink(resolveFromRef(from), resolveToRef(to)),
+            [`remove${capitalizedTo}From${capitalizedFrom}`]: (from, to) => removeLink(resolveFromRef(from), resolveToRef(to)),
+            [`move${capitalizedTo}To${capitalizedFrom}`]: (to, newFrom) => moveTo(resolveToRef(to), resolveFromRef(newFrom)),
+        };
+        // A set of the input side's ids keys the other side. Collect ALL return-entities per set so the
+        // lookup can hand back every match; shape to single or array by the same rule as the type layer.
+        // JSON-encode the sorted ids so the key is collision-proof: an id that contains a plain
+        // delimiter (`a|b`) can't merge with another set, since every element is quoted and escaped.
+        const keyOf = (ids) => JSON.stringify(ids.map(String).sort());
+        const isFixedCount = (count) => typeof count === 'number' && count >= 2;
+        const isMulti = (count) => count !== 1;
+        const addSetLookup = (returnName, returnPlural, returnCount, inputPlural, inputCount, sourceMapKey, returnEntityMapKey, readInputId) => {
+            const index = computed(() => {
+                const built = {};
+                const source = innerStore[sourceMapKey]();
+                Object.keys(source).forEach((returnId) => {
+                    const key = keyOf(source[returnId]);
+                    built[key] = addUnique(built[key], returnId);
+                });
+                return built;
+            }, /* @ts-ignore */
+            ...(ngDevMode ? [{ debugName: "index" }] : /* istanbul ignore next */ []));
+            const resolveInputRef = toRefResolver(readInputId);
+            const lookupIds = (refs) => index()[keyOf(refs.map((ref) => resolveInputRef(ref)))] ?? [];
+            const single = isFixedCount(inputCount) || returnCount === 1;
+            const entityLead = single ? returnName : returnPlural;
+            const idLead = single ? `${returnName}Id` : `${returnName}Ids`;
+            const capitalizedInputPlural = capitalize(inputPlural);
+            methods[`${entityLead}By${capitalizedInputPlural}`] = (...refs) => {
+                const entities = resolveEntities(lookupIds(refs), returnEntityMapKey);
+                return single ? entities[0] : entities;
+            };
+            methods[`${idLead}By${capitalizedInputPlural}`] = (...refs) => {
+                const ids = lookupIds(refs);
+                return single ? ids[0] : ids;
+            };
+        };
+        // Ordering + indexOf over an owner's member list. The owner's ordered members are its entry in the
+        // manual links map; mergeLinks keeps that array's order ahead of the FK-derived links, so writing it
+        // sets the order the get-by lookup returns. With syncForeignKeys the same order is also written into
+        // the owner entity's array foreign key (when it holds one). swap/reorder/move share this core, keyed
+        // by owner id.
+        const makeOrderingCore = (linksKey, membersOf, writeOwnerOrder) => {
+            const writeOrder = (ownerId, orderedIds) => {
+                patchState(innerStore, { [linksKey]: { ...innerStore[linksKey](), [ownerId]: orderedIds } });
+                writeOwnerOrder(ownerId, orderedIds);
+            };
+            return {
+                swap: (label, ownerId, aId, bId) => {
+                    const current = [...membersOf(ownerId)];
+                    const indexA = current.indexOf(aId);
+                    const indexB = current.indexOf(bId);
+                    if (indexA === -1 || indexB === -1) {
+                        console.warn(`signalkin: ${label} — both members must belong to that owner; call ignored.`);
+                        return;
+                    }
+                    [current[indexA], current[indexB]] = [current[indexB], current[indexA]];
+                    writeOrder(ownerId, current);
+                },
+                reorder: (label, ownerId, orderedIds) => {
+                    const current = membersOf(ownerId);
+                    const isFullPermutation = orderedIds.length === current.length &&
+                        new Set(orderedIds).size === orderedIds.length &&
+                        orderedIds.every((id) => current.includes(id));
+                    if (!isFullPermutation) {
+                        console.warn(`signalkin: ${label} — pass that owner's complete member set exactly once; call ignored.`);
+                        return;
+                    }
+                    writeOrder(ownerId, orderedIds);
+                },
+                move: (ownerId, memberId, index) => {
+                    const current = [...membersOf(ownerId)];
+                    const currentIndex = current.indexOf(memberId);
+                    if (currentIndex === -1)
+                        return;
+                    const target = Math.max(0, Math.min(index, current.length - 1));
+                    current.splice(currentIndex, 1);
+                    current.splice(target, 0, memberId);
+                    writeOrder(ownerId, current);
+                },
+            };
+        };
+        // One-arg family: the member has exactly one owner (owner side count 1), so it is inferred and only
+        // the member is passed. indexOf<Owner><Member>(member) + swap/reorder/move<Owner><Member(s)>.
+        const installOrdering = (capitalizedOwner, capitalizedMember, capitalizedMemberPlural, linksKey, membersOf, ownerOf, resolveMember, writeOwnerOrder) => {
+            const core = makeOrderingCore(linksKey, membersOf, writeOwnerOrder);
+            methods[`indexOf${capitalizedOwner}${capitalizedMember}`] = (member) => {
+                const memberId = resolveMember(member);
+                return membersOf(ownerOf(memberId)).indexOf(memberId);
+            };
+            methods[`swap${capitalizedOwner}${capitalizedMemberPlural}`] = (memberA, memberB) => {
+                const aId = resolveMember(memberA);
+                const ownerId = ownerOf(aId);
+                if (!hasId(ownerId))
+                    return;
+                core.swap(`swap${capitalizedOwner}${capitalizedMemberPlural}`, ownerId, aId, resolveMember(memberB));
+            };
+            methods[`reorder${capitalizedOwner}${capitalizedMemberPlural}`] = (orderedMembers) => {
+                const orderedIds = (orderedMembers ?? []).map(resolveMember).filter(hasId);
+                const ownerId = ownerOf(orderedIds[0]);
+                if (!hasId(ownerId))
+                    return;
+                core.reorder(`reorder${capitalizedOwner}${capitalizedMemberPlural}`, ownerId, orderedIds);
+            };
+            methods[`move${capitalizedOwner}${capitalizedMember}ToIndex`] = (member, index) => {
+                const memberId = resolveMember(member);
+                const ownerId = ownerOf(memberId);
+                if (!hasId(ownerId))
+                    return;
+                core.move(ownerId, memberId, index);
+            };
+        };
+        // By-family: the member has MORE THAN ONE owner (owner side not count 1) and belongs to more than
+        // one of each owner (member side multi — fixed 2+ or 'many'), so the owner can't be inferred and is
+        // named as the last argument.
+        const installByOrdering = (capitalizedOwner, capitalizedMember, capitalizedMemberPlural, linksKey, membersOf, resolveOwner, resolveMember, writeOwnerOrder) => {
+            const core = makeOrderingCore(linksKey, membersOf, writeOwnerOrder);
+            methods[`indexOf${capitalizedMember}By${capitalizedOwner}`] = (member, owner) => membersOf(resolveOwner(owner)).indexOf(resolveMember(member));
+            methods[`swap${capitalizedMemberPlural}By${capitalizedOwner}`] = (memberA, memberB, owner) => {
+                const ownerId = resolveOwner(owner);
+                if (!hasId(ownerId))
+                    return;
+                core.swap(`swap${capitalizedMemberPlural}By${capitalizedOwner}`, ownerId, resolveMember(memberA), resolveMember(memberB));
+            };
+            methods[`reorder${capitalizedMemberPlural}By${capitalizedOwner}`] = (orderedMembers, owner) => {
+                const ownerId = resolveOwner(owner);
+                if (!hasId(ownerId))
+                    return;
+                core.reorder(`reorder${capitalizedMemberPlural}By${capitalizedOwner}`, ownerId, (orderedMembers ?? []).map(resolveMember).filter(hasId));
+            };
+            methods[`move${capitalizedMember}By${capitalizedOwner}ToIndex`] = (member, index, owner) => {
+                const ownerId = resolveOwner(owner);
+                if (!hasId(ownerId))
+                    return;
+                core.move(ownerId, resolveMember(member), index);
+            };
+        };
+        // Filtered directional lookup: the owners where the member sits at EXACTLY `index` in the owner's
+        // ordered member list. Installed in the same By-family cases as installByOrdering (member 'many',
+        // owner multi) — a single-owner member has no choice of slot to filter on. Returns entities and ids.
+        const installIndexedLookup = (ownerName, ownerPlural, capitalizedMember, ownerEntityMapKey, membersOf, ownersOf, resolveMember) => {
+            const ownerIdsAtIndex = (member, index) => {
+                const memberId = resolveMember(member);
+                return ownersOf(memberId).filter((ownerId) => membersOf(ownerId)[index] === memberId);
+            };
+            methods[`${ownerPlural}By${capitalizedMember}AtIndex`] = (member, index) => resolveEntities(ownerIdsAtIndex(member, index), ownerEntityMapKey);
+            methods[`${ownerName}IdsBy${capitalizedMember}AtIndex`] = (member, index) => ownerIdsAtIndex(member, index);
+        };
+        // Direction owner = from, members = to (e.g. a feature's options, or an option's cells). A single
+        // owner is inferred (one-arg installOrdering); a multi owner is named explicitly (installByOrdering),
+        // now for any multi member side (fixed count 2+ or 'many'), not just 'many'.
+        if (isMulti(to.count)) {
+            if (fromIsSingle) {
+                installOrdering(capitalizedFrom, capitalizedTo, capitalize(toPlural), forwardLinksKey, (ownerId) => toIdsByFrom(ownerId), (memberId) => fromIdsByTo(memberId)[0], resolveToRef, writeFromOwnerOrder);
+            }
+            else {
+                installByOrdering(capitalizedFrom, capitalizedTo, capitalize(toPlural), forwardLinksKey, (ownerId) => toIdsByFrom(ownerId), resolveFromRef, resolveToRef, writeFromOwnerOrder);
+            }
+        }
+        // Direction owner = to, members = from.
+        if (isMulti(from.count)) {
+            if (toIsSingle) {
+                installOrdering(capitalizedTo, capitalizedFrom, capitalize(fromPlural), reverseLinksKey, (ownerId) => fromIdsByTo(ownerId), (memberId) => toIdsByFrom(memberId)[0], resolveFromRef, writeToOwnerOrder);
+            }
+            else {
+                installByOrdering(capitalizedTo, capitalizedFrom, capitalize(fromPlural), reverseLinksKey, (ownerId) => fromIdsByTo(ownerId), resolveToRef, resolveFromRef, writeToOwnerOrder);
+            }
+        }
+        // AtIndex filtered lookups apply whenever BOTH sides are multi: the owner holds an ordered array of
+        // 2+ members and the member belongs to more than one owner, so it can sit at a different slot in
+        // each. This is broader than the 'many'-only by-ordering gate above — a fixed-count member (a cell's
+        // two optionIds, an ensemble's four musicians) still gets it. Both directions.
+        if (isMulti(from.count) && isMulti(to.count)) {
+            installIndexedLookup(fromName, fromPlural, capitalizedTo, fromEntityMapKey, (ownerId) => toIdsByFrom(ownerId), (memberId) => fromIdsByTo(memberId), resolveToRef);
+            installIndexedLookup(toName, toPlural, capitalizedFrom, toEntityMapKey, (ownerId) => fromIdsByTo(ownerId), (memberId) => toIdsByFrom(memberId), resolveFromRef);
+        }
+        if (compositeLookups) {
+            // from's id-set keys the to-side (source: to -> its froms).
+            if (isMulti(from.count)) {
+                addSetLookup(toName, toPlural, to.count, fromPlural, from.count, reverseMapKey, toEntityMapKey, readFromPrimaryId);
+            }
+            // to's id-set keys the from-side (source: from -> its tos).
+            if (isMulti(to.count)) {
+                addSetLookup(fromName, fromPlural, from.count, toPlural, to.count, forwardMapKey, fromEntityMapKey, readToPrimaryId);
+            }
+        }
+        return methods;
+    }));
+    return feature;
+};
+
+/**
+ * Read-only lookups between two collections that share no foreign key, by walking the intermediary collection(s) between them (`through` a single name or an ordered list); returns arrays both directions.
+ *
+ * @example
+ * signalStore(
+ *   withEntities(libraryConfig), withEntities(shelfConfig), withEntities(bookConfig),
+ *   withEntityRelationship({ collection: 'library', count: 1 }, { collection: 'shelf', count: 'many' }),
+ *   withEntityRelationship({ collection: 'shelf', count: 1 }, { collection: 'book', count: 'many' }),
+ *   withTransitiveRelationship({ from: 'library', to: 'book', through: 'shelf' }),
+ * );
+ * // booksByLibrary(library | id) -> Book[]
+ * // librariesByBook(book | id) -> Library[]
+ */
+const withTransitiveRelationship = (config) => {
+    const { from, to, through } = config;
+    const fromPlural = config.fromPlural ?? `${from}s`;
+    const toPlural = config.toPlural ?? `${to}s`;
+    const path = [from, ...(Array.isArray(through) ? through : [through]), to];
+    // Adjacency map keys along the path, forward (from→to) and reverse (to→from).
+    const forwardMapKeys = path.slice(0, -1).map((hop, index) => `${hop}${capitalize(path[index + 1])}Map`);
+    const reverseMapKeys = path.slice(1).map((hop, index) => `${hop}${capitalize(path[index])}Map`).reverse();
+    const fromEntityMapKey = `${from}EntityMap`;
+    const toEntityMapKey = `${to}EntityMap`;
+    const readFromId = toIdReader(config.selectFromId, 'id');
+    const readToId = toIdReader(config.selectToId, 'id');
+    const capitalizedFrom = capitalize(from);
+    const capitalizedTo = capitalize(to);
+    const feature = signalStoreFeature(withMethods((innerStore) => {
+        // Walk the chain of adjacency maps, flattening + deduping ids hop by hop.
+        const walk = (startId, mapKeys) => hasId(startId)
+            ? mapKeys.reduce((ids, mapKey) => {
+                if (typeof innerStore[mapKey] !== 'function') {
+                    throw new Error(`signalkin: '${mapKey}' is not on the store — a transitive relationship needs the direct ` +
+                        `withEntityRelationship for every hop on its path registered before it (path: ${path.join(' → ')}).`);
+                }
+                const map = innerStore[mapKey]();
+                return Array.from(new Set(ids.flatMap((id) => map[id] ?? [])));
+            }, [startId])
+            : [];
+        const resolve = (ids, entityMapKey) => ids.map((id) => innerStore[entityMapKey]()[id]).filter((entity) => entity !== undefined);
+        const toIdsByFrom = (fromId) => walk(fromId, forwardMapKeys);
+        const fromIdsByTo = (toId) => walk(toId, reverseMapKeys);
+        const resolveFromRef = toRefResolver(readFromId);
+        const resolveToRef = toRefResolver(readToId);
+        const methods = {
+            [`${toPlural}By${capitalizedFrom}`]: (from) => resolve(toIdsByFrom(resolveFromRef(from)), toEntityMapKey),
+            [`${to}IdsBy${capitalizedFrom}`]: (from) => toIdsByFrom(resolveFromRef(from)),
+            [`${fromPlural}By${capitalizedTo}`]: (to) => resolve(fromIdsByTo(resolveToRef(to)), fromEntityMapKey),
+            [`${from}IdsBy${capitalizedTo}`]: (to) => fromIdsByTo(resolveToRef(to)),
+        };
+        return methods;
+    }));
+    return feature;
+};
+
+/*
+ * Public API Surface of signalkin
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { withEntityAccessors, withEntityRelationship, withTransitiveRelationship };
+//# sourceMappingURL=signalkin.mjs.map