Flurryx

flurryx

Signal-first reactive state management for Angular. RxJS in, signals out.

When to Activate

• Build/modify state with Store, syncToStore, syncToKeyedStore
• Add facades/services exposing flurryx-backed signals
• Scaffold feature modules using flurryx for async state, caching, keyed resources
• Per-entity caches via KeyedResourceData<TKey, TValue>
• Mirroring/derivation: mirror, mirrorSelf, derive, deriveSelf, mirrorKeyed, mirrorKey, deriveKey, collectKeyed
• Channel persistence, history, replay, dead-letter recovery
• Reviewing AI-generated Angular code for flurryx correctness

Imports

// main API
import {
  Store, BaseStore, LazyStore,
  syncToStore, syncToKeyedStore,
  SkipIfCached, Loading,
  clearAllStores,
  mirrorKey, deriveKey, collectKeyed,
  cloneValue, createSnapshotRestorePatch,
  createInMemoryStoreMessageChannel,
  createStorageStoreMessageChannel,
  createLocalStorageStoreMessageChannel,
  createSessionStorageStoreMessageChannel,
  createCompositeStoreMessageChannel,
  isKeyedResourceData, createKeyedResourceData, isAnyKeyLoading,
  CACHE_NO_TIMEOUT, DEFAULT_CACHE_TTL_MS,
  defaultErrorNormalizer,
} from 'flurryx';

import type {
  ResourceState, StoreEnum, ResourceStatus, ResourceErrors,
  KeyedResourceData, KeyedResourceKey,
  StoreSignal, KeyedStoreSignal, KeyedResourceState, ValueOrSignal,
  StoreOptions, StoreCacheInvalidateEvent,
  MirrorOptions, DeriveOptions, CollectKeyedOptions,
  SyncToStoreOptions, SyncToKeyedStoreOptions, ErrorNormalizer,
  // history
  StoreHistory, StoreHistoryEntry,
  StoreDeadLetterEntry, StoreDeadLetterCommand, StoreDeadLetterMeta,
  DeadLetterCommandResolverResult,
  // messages
  StoreMessage, StoreSnapshot, StoreMessageStatus,
  UpdateStoreMessage, ClearStoreMessage, ClearAllStoreMessage,
  StartLoadingStoreMessage, StopLoadingStoreMessage,
  UpdateKeyedOneStoreMessage, ClearKeyedOneStoreMessage,
  StartKeyedLoadingStoreMessage, EnsureKeyedSlotStoreMessage,
  // channels
  StoreMessageRecord, StoreMessageChannel,
  StoreMessageChannelStorage, StoreMessageChannelOptions,
  CompositeStoreMessageChannelOptions,
  StorageStoreMessageChannelOptions,
  BrowserStorageStoreMessageChannelOptions,
} from 'flurryx';

// HTTP-only — pulls @angular/common/http
import { httpErrorNormalizer } from 'flurryx/http';

Prefer flurryx. Use flurryx/http only for httpErrorNormalizer. Avoid direct @flurryx/core | @flurryx/store | @flurryx/rx unless host already depends.

Hard Rules

• Never any
• Components read signals only. Facade/service owns subscriptions + writes
• Prefer Store.for<Config>().build() interface builder
• UPPER_SNAKE_CASE keys: LIST, DETAIL, ITEMS
• @SkipIfCached outermost, @Loading directly beneath
• Use @SkipIfCached only if cache hits are intended; else omit
• Keyed resources -> syncToKeyedStore, not hand-rolled Record updates
• Don't subclass BaseStore directly
• Don't call component methods in templates -> use computed

Core Flow

Observable -> syncToStore / syncToKeyedStore -> Store signal -> Template

ResourceState<T>

Every slot wraps ResourceState<T>:

interface ResourceState<T> {
  isLoading?: boolean;
  data?: T;
  status?: 'Success' | 'Error';
  errors?: Array<{ code: string; message: string }>;
}

Lifecycle: idle -> loading -> Success | Error.

KeyedResourceData

Per-entity cache:

type KeyedResourceData<TKey extends string | number, TValue> =
  Partial<Record<TKey, ResourceState<TValue>>>;

Helpers:

• createKeyedResourceData<TKey, TValue>() -> {}
• isKeyedResourceData(val) -> type guard
• isAnyKeyLoading(data) -> bool

Store Builder

Interface form (preferred)

interface ProductStoreConfig {
  LIST: Product[];
  DETAIL: Product;
  ITEMS: KeyedResourceData<string, Item>;
}

export const ProductStore = Store.for<ProductStoreConfig>().build();

Naming: <Feature>StoreConfig + <Feature>Store. Slots are raw types; flurryx wraps in ResourceState<T>.

Enum-constrained form

const Keys = { LIST: 'LIST', DETAIL: 'DETAIL' } as const;
export const ProductStore = Store.for(Keys)
  .resource('LIST').as<Product[]>()
  .resource('DETAIL').as<Product>()
  .build();

.build() only callable when all enum keys defined.

Fluent form

export const ProductStore = Store
  .resource('LIST').as<Product[]>()
  .resource('DETAIL').as<Product>()
  .build();

Builder methods (all forms)

• .mirror(sourceToken, sourceKey, targetKey?) -> 1:1 cross-store mirror
• .mirrorSelf(sourceKey, targetKey) -> alias inside same store; keys must differ
• .derive(sourceToken, sourceKey, targetKey?, { mapData }) -> map source data into target slot
• .deriveSelf(sourceKey, targetKey, { mapData }) -> derived alias inside same store
• .mirrorKeyed(sourceToken, sourceKey, { extractId }, targetKey?) -> aggregate single-entity fetches into keyed slot
• .build(options?: StoreOptions) -> InjectionToken registered providedIn: 'root'

StoreOptions extends StoreMessageChannelOptions -> supply channel to override default in-memory channel.

IStore API

store.get(key) returns:

• non-keyed slot -> Signal<ResourceState<T>>
• keyed slot -> KeyedStoreSignal<TData, K> = signal + .for(resourceKey | Signal<resourceKey>) -> Signal<ResourceState<TValue>>

Writes (publish broker messages)

• update(key, partial, options?) -> merge partial; options.deadLetter?: StoreDeadLetterMeta
• clear(key) -> reset slot to idle
• clearAll() -> reset every slot
• startLoading(key) / stopLoading(key)
• updateKeyedOne(key, resourceKey, entity) -> sets entity status Success, recomputes top-level isLoading
• clearKeyedOne(key, resourceKey) -> remove single keyed entry
• startKeyedLoading(key, resourceKey) -> mark single key loading

Cache invalidation

• invalidateCacheFor(key) -> invalidate slot cache only (state untouched)
• invalidateCacheFor(key, resourceKey) -> invalidate one keyed entry's cache

Hooks

• onUpdate(key, (next, prev) => …) -> () => void cleanup
• onCacheInvalidate(key, ({ key, resourceKey }) => …) -> cleanup
• Hook errors are caught + rethrown via queueMicrotask/AggregateError

History / Replay

• replay(id | ids[]) -> re-execute persisted channel messages -> int (acked count)
• restoreStoreAt(index) -> snapshot navigation (no message)
• restoreResource(key, index?) -> restore single key from snapshot
• undo() / redo() -> bool
• getHistory() / getHistory(key) -> readonly entries
• getMessages() / getMessages(key) -> channel records
• getDeadLetters() -> dead-letter entries
• replayDeadLetter(id) -> bool
• replayDeadLetters() -> int (acked)
• replayDeadLetterCommand(id, async resolver -> { resolved, clear }) -> Promise<bool>
• getCurrentIndex() -> int

Reactive signals on store

• history: Signal<readonly StoreHistoryEntry[]>
• messages: Signal<readonly StoreMessageRecord[]>
• currentIndex: Signal<number>
• keys: Signal<readonly StoreKey[]> (LazyStore: grows on first access)

Global

• clearAllStores() -> calls clearAll() on every tracked store. Use for logout/tenant switch.

Rx Operators

syncToStore

this.api.getProducts().pipe(
  syncToStore(this.store, 'LIST', {
    completeOnFirstEmission: true,           // default true (take(1))
    callbackAfterComplete: () => {},
    errorNormalizer: defaultErrorNormalizer, // default
    deadLetterCommand: { type: '...', payload: {} },
  })
).subscribe();

Success -> { data, isLoading: false, status: 'Success', errors: undefined }. Error -> { data: undefined, isLoading: false, status: 'Error', errors: normalized } + DLQ meta from HTTP-like errors.

syncToKeyedStore

this.api.getInvoice(id).pipe(
  syncToKeyedStore(this.store, 'ITEMS', id, {
    mapResponse: (r) => r.data,    // optional response unwrap
    completeOnFirstEmission: true,
    callbackAfterComplete: () => {},
    errorNormalizer,
    deadLetterCommand,
  })
).subscribe();

Bootstraps isLoading: true for that key on subscribe (via defer). Per-key Success/Error; recomputes top-level isLoading from remaining keys.

Decorators

@SkipIfCached

@SkipIfCached(
  storeKey,
  (i) => i.store,
  returnObservable = false,
  timeoutMs = DEFAULT_CACHE_TTL_MS,  // CACHE_NO_TIMEOUT for infinite
)

Cache hit (skip) when: status === 'Success' OR isLoading === true, args match (JSON.stringify), TTL not expired. Cache miss when: idle, status === 'Error', expired, or args changed. Keyed: if first arg is string|number AND slot is KeyedResourceData, tracks cache per resourceKey automatically. returnObservable: true -> uses shareReplay({ bufferSize: 1, refCount: true }) for in-flight dedup; method must return Observable.

@Loading

@Loading(storeKey, (i) => i.store)

Calls startLoading(key) before method. If first arg is string|number and store has startKeyedLoading, calls startKeyedLoading(key, resourceKey) instead.

Composition

@SkipIfCached MUST be outermost (short-circuits before loading). @Loading above @SkipIfCached -> potential infinite loading loops.

Standalone Functions

mirrorKey

mirrorKey(sourceStore, sourceKey, targetStore, targetKey?, options?: MirrorOptions)
// MirrorOptions: { destroyRef?, direction?: 'bidirectional' | 'source-to-target' }
// Default direction: 'bidirectional' — updates flow both ways with loop guard.
// Set direction: 'source-to-target' for one-way mirroring.
// returns cleanup () => void

deriveKey

deriveKey(source, sourceKey, target, targetKey, {
  mapData: (data, state) => mappedData,
  destroyRef?,
})
// returns cleanup. Mirrors isLoading/status/errors, maps data.

collectKeyed

collectKeyed(source, sourceKey, target, targetKey?, {
  extractId: (entity | undefined) => key | undefined,
  destroyRef?,
})
// CollectKeyedOptions. Aggregates single-entity emissions into keyed cache.