@logixjs/react 0.1.0

package/dist/Hooks.d.cts

@@ -0,0 +1,77 @@
+import { Layer, ManagedRuntime, Effect } from 'effect';
+export { c as useDispatch, a as useLocalModule, u as useModule, b as useSelector } from './useDispatch-CnO5-66H.cjs';
+import React from 'react';
+import * as Logix from '@logixjs/core';
+import { c as ModuleRef, b as ModuleDispatchersOfShape } from './ModuleRef-wZSQ3Wwo.cjs';
+export { M as ModuleActions, a as ModuleDispatchers } from './ModuleRef-wZSQ3Wwo.cjs';
+
+interface UseRuntimeOptions {
+    readonly layer?: Layer.Layer<any, any, never>;
+    readonly layers?: ReadonlyArray<Layer.Layer<any, any, never>>;
+}
+declare function useRuntime(): ManagedRuntime.ManagedRuntime<any, any>;
+declare function useRuntime(options: UseRuntimeOptions): ManagedRuntime.ManagedRuntime<any, any>;
+
+/**
+ * Creates a local ModuleRuntime from an already assembled Module Layer (e.g. RegionLive).
+ *
+ * Use cases:
+ * - On the effect side, you already built the full Layer via `Module.live(initial, ...logics)`.
+ * - A React component wants to "just consume" that Layer without caring about initial/logics details.
+ */
+declare function useLayerModule<Id extends string, Sh extends Logix.AnyModuleShape>(module: Logix.ModuleTagType<Id, Sh>, layer: Layer.Layer<Logix.ModuleRuntime<Logix.StateOf<Sh>, Logix.ActionOf<Sh>>, never, any>, deps?: React.DependencyList): ModuleRef<Logix.StateOf<Sh>, Logix.ActionOf<Sh>>;
+
+/**
+ * A hook to manage a dynamic list of Module instances.
+ * It ensures that the Module instance for a given ID remains stable across renders,
+ * which is crucial for preserving the identity of the module (and its state/subscriptions).
+ *
+ * @param items The source data array.
+ * @param keyFn A function to extract a unique key (ID) from an item.
+ * @param factory A function to create a new Module instance for a given ID and item.
+ * @returns An array of Module instances corresponding to the items.
+ */
+declare function useModuleList<T, M>(items: T[], keyFn: (item: T) => string, factory: (id: string, item: T) => M): M[];
+
+/**
+ * Resolves a child module runtime provided by imports from the "parent module instance scope".
+ *
+ * Typical usage:
+ * - const host = useModule(HostImpl, { key })
+ * - const query = useImportedModule(host, SearchQuery.tag)
+ * - const status = useSelector(query, s => s.search.status)
+ */
+declare function useImportedModule<Id extends string, Sh extends Logix.AnyModuleShape>(parent: Logix.ModuleRuntime<any, any> | ModuleRef<any, any>, module: Logix.ModuleTagType<Id, Sh>): ModuleRef<Logix.StateOf<Sh>, Logix.ActionOf<Sh>, keyof Sh['actionMap'] & string, Logix.ModuleTagType<Id, Sh>, ModuleDispatchersOfShape<Sh>>;
+
+interface UseProcessesOptions {
+    /**
+     * Stable identifier for a UI subtree scope.
+     *
+     * - Recommended: a domain boundary id (e.g. route / feature key) for diagnostics and filtering.
+     * - Default: derived from React.useId() (stable for the same tree position; reusable under StrictMode).
+     */
+    readonly subtreeId?: string;
+    /**
+     * Keep-alive time (ms) after unmount, to absorb StrictMode / Suspense jitter:
+     * - We do not stop immediately on unmount; we close the scope after gcTime (and refCount is still 0).
+     */
+    readonly gcTime?: number;
+    /**
+     * Restart semantics for stop -> start:
+     * - switch (default): if the previous instance is still stopping, ensure the "current install intent" resumes after stopping finishes.
+     * - exhaust: ignore this install while stopping; it will only resume on the next install.
+     */
+    readonly mode?: 'switch' | 'exhaust';
+    readonly deps?: React.DependencyList;
+}
+declare function useProcesses(processes: ReadonlyArray<Effect.Effect<void, any, any>>, options?: UseProcessesOptions): void;
+
+/**
+ * `shallow`: a common `useSelector(..., equalityFn)` implementation.
+ *
+ * Semantics: shallow-compare Array / Object / Map / Set (uses `Object.is` for leaf values),
+ * useful when a selector returns a "new object/array" with unchanged contents to skip meaningless re-renders.
+ */
+declare const shallow: <T>(previous: T, next: T) => boolean;
+
+export { ModuleDispatchersOfShape, ModuleRef, type UseProcessesOptions, type UseRuntimeOptions, shallow, useImportedModule, useLayerModule, useModuleList, useProcesses, useRuntime };

package/dist/Hooks.d.ts

@@ -0,0 +1,77 @@
+import { Layer, ManagedRuntime, Effect } from 'effect';
+export { c as useDispatch, a as useLocalModule, u as useModule, b as useSelector } from './useDispatch-BnzYVkRE.js';
+import React from 'react';
+import * as Logix from '@logixjs/core';
+import { c as ModuleRef, b as ModuleDispatchersOfShape } from './ModuleRef-wZSQ3Wwo.js';
+export { M as ModuleActions, a as ModuleDispatchers } from './ModuleRef-wZSQ3Wwo.js';
+
+interface UseRuntimeOptions {
+    readonly layer?: Layer.Layer<any, any, never>;
+    readonly layers?: ReadonlyArray<Layer.Layer<any, any, never>>;
+}
+declare function useRuntime(): ManagedRuntime.ManagedRuntime<any, any>;
+declare function useRuntime(options: UseRuntimeOptions): ManagedRuntime.ManagedRuntime<any, any>;
+
+/**
+ * Creates a local ModuleRuntime from an already assembled Module Layer (e.g. RegionLive).
+ *
+ * Use cases:
+ * - On the effect side, you already built the full Layer via `Module.live(initial, ...logics)`.
+ * - A React component wants to "just consume" that Layer without caring about initial/logics details.
+ */
+declare function useLayerModule<Id extends string, Sh extends Logix.AnyModuleShape>(module: Logix.ModuleTagType<Id, Sh>, layer: Layer.Layer<Logix.ModuleRuntime<Logix.StateOf<Sh>, Logix.ActionOf<Sh>>, never, any>, deps?: React.DependencyList): ModuleRef<Logix.StateOf<Sh>, Logix.ActionOf<Sh>>;
+
+/**
+ * A hook to manage a dynamic list of Module instances.
+ * It ensures that the Module instance for a given ID remains stable across renders,
+ * which is crucial for preserving the identity of the module (and its state/subscriptions).
+ *
+ * @param items The source data array.
+ * @param keyFn A function to extract a unique key (ID) from an item.
+ * @param factory A function to create a new Module instance for a given ID and item.
+ * @returns An array of Module instances corresponding to the items.
+ */
+declare function useModuleList<T, M>(items: T[], keyFn: (item: T) => string, factory: (id: string, item: T) => M): M[];
+
+/**
+ * Resolves a child module runtime provided by imports from the "parent module instance scope".
+ *
+ * Typical usage:
+ * - const host = useModule(HostImpl, { key })
+ * - const query = useImportedModule(host, SearchQuery.tag)
+ * - const status = useSelector(query, s => s.search.status)
+ */
+declare function useImportedModule<Id extends string, Sh extends Logix.AnyModuleShape>(parent: Logix.ModuleRuntime<any, any> | ModuleRef<any, any>, module: Logix.ModuleTagType<Id, Sh>): ModuleRef<Logix.StateOf<Sh>, Logix.ActionOf<Sh>, keyof Sh['actionMap'] & string, Logix.ModuleTagType<Id, Sh>, ModuleDispatchersOfShape<Sh>>;
+
+interface UseProcessesOptions {
+    /**
+     * Stable identifier for a UI subtree scope.
+     *
+     * - Recommended: a domain boundary id (e.g. route / feature key) for diagnostics and filtering.
+     * - Default: derived from React.useId() (stable for the same tree position; reusable under StrictMode).
+     */
+    readonly subtreeId?: string;
+    /**
+     * Keep-alive time (ms) after unmount, to absorb StrictMode / Suspense jitter:
+     * - We do not stop immediately on unmount; we close the scope after gcTime (and refCount is still 0).
+     */
+    readonly gcTime?: number;
+    /**
+     * Restart semantics for stop -> start:
+     * - switch (default): if the previous instance is still stopping, ensure the "current install intent" resumes after stopping finishes.
+     * - exhaust: ignore this install while stopping; it will only resume on the next install.
+     */
+    readonly mode?: 'switch' | 'exhaust';
+    readonly deps?: React.DependencyList;
+}
+declare function useProcesses(processes: ReadonlyArray<Effect.Effect<void, any, any>>, options?: UseProcessesOptions): void;
+
+/**
+ * `shallow`: a common `useSelector(..., equalityFn)` implementation.
+ *
+ * Semantics: shallow-compare Array / Object / Map / Set (uses `Object.is` for leaf values),
+ * useful when a selector returns a "new object/array" with unchanged contents to skip meaningless re-renders.
+ */
+declare const shallow: <T>(previous: T, next: T) => boolean;
+
+export { ModuleDispatchersOfShape, ModuleRef, type UseProcessesOptions, type UseRuntimeOptions, shallow, useImportedModule, useLayerModule, useModuleList, useProcesses, useRuntime };

package/dist/Hooks.js

@@ -0,0 +1,27 @@
+import {
+  useDispatch,
+  useImportedModule,
+  useLayerModule,
+  useLocalModule,
+  useModuleList,
+  useProcesses
+} from "./chunk-PYWHL7TA.js";
+import {
+  shallow,
+  useModule,
+  useRuntime,
+  useSelector
+} from "./chunk-UFFCJGSZ.js";
+import "./chunk-2WFULYPJ.js";
+export {
+  shallow,
+  useDispatch,
+  useImportedModule,
+  useLayerModule,
+  useLocalModule,
+  useModule,
+  useModuleList,
+  useProcesses,
+  useRuntime,
+  useSelector
+};

package/dist/ModuleRef-wZSQ3Wwo.d.cts

@@ -0,0 +1,73 @@
+import * as Logix from '@logixjs/core';
+
+type Dispatch<A> = ((action: A) => void) & {
+    readonly batch: (actions: ReadonlyArray<A>) => void;
+    readonly lowPriority: (action: A) => void;
+};
+type ActionArgs<P> = [P] extends [void] ? [] | [P] : [P];
+type ActionFn<P, Out> = (...args: ActionArgs<P>) => Out;
+type ActionTag<A> = A extends {
+    readonly _tag: infer T;
+} ? T : A extends {
+    readonly type: infer T;
+} ? T : never;
+type ActionTags<A> = Extract<ActionTag<A>, string>;
+type ActionPayload<A, K> = Extract<A, {
+    readonly _tag: K;
+} | {
+    readonly type: K;
+}> extends {
+    readonly payload?: infer P;
+} ? P : never;
+type AnyActionToken = Logix.Action.ActionToken<string, any, any>;
+type ModuleDispatchersOfShape<Sh extends Logix.AnyModuleShape> = Sh['actionMap'];
+type ModuleActions<A, Tags extends string = ActionTags<A>> = {
+    readonly dispatch: Dispatch<A>;
+} & ([ActionTags<A>] extends [never] ? {} : {
+    readonly [K in Tags & ActionTags<A>]: ActionFn<ActionPayload<A, K>, void>;
+});
+type ActionMapOfDef<Def> = Def extends {
+    readonly actions: infer ActionMap;
+} ? ActionMap : never;
+type ModuleDispatchers<A, Tags extends string = ActionTags<A>, Def = unknown> = [ActionMapOfDef<Def>] extends [
+    never
+] ? [ActionTags<A>] extends [never] ? {} : {
+    readonly [K in Tags & ActionTags<A>]: ActionFn<ActionPayload<A, K>, Extract<A, {
+        readonly _tag: K;
+    } | {
+        readonly type: K;
+    }>>;
+} : ActionMapOfDef<Def> extends Record<string, AnyActionToken> ? ActionMapOfDef<Def> : [ActionTags<A>] extends [never] ? {} : {
+    readonly [K in Tags & ActionTags<A>]: ActionFn<ActionPayload<A, K>, Extract<A, {
+        readonly _tag: K;
+    } | {
+        readonly type: K;
+    }>>;
+};
+interface ModuleImports {
+    readonly get: <Id extends string, Sh extends Logix.AnyModuleShape>(module: Logix.ModuleTagType<Id, Sh>) => ModuleRef<Logix.StateOf<Sh>, Logix.ActionOf<Sh>, keyof Sh['actionMap'] & string, Logix.ModuleTagType<Id, Sh>, ModuleDispatchersOfShape<Sh>>;
+}
+interface ModuleRef<S, A, Tags extends string = ActionTags<A>, Def = unknown, Dispatchers = ModuleDispatchers<A, Tags, Def>> {
+    /**
+     * Definition anchor (typically a ModuleTag) for reflecting actions/reducers/source and other metadata.
+     * - DX: when `runtime.actions.*` can't jump to source, use `ref.def?.reducers?.xxx` / `ref.def?.actions.xxx` to locate definitions quickly.
+     */
+    readonly def?: Def;
+    readonly runtime: Logix.ModuleRuntime<S, A>;
+    readonly dispatch: Dispatch<A>;
+    readonly actions: ModuleActions<A, Tags>;
+    readonly dispatchers: Dispatchers;
+    /**
+     * Fractal module imports sugar:
+     * - host.imports.get(ChildModule) resolves a child module instance within the host instance scope.
+     * - strict by default: throws when scope is missing, avoiding accidentally routing to a global instance.
+     */
+    readonly imports: ModuleImports;
+    readonly getState: Logix.ModuleRuntime<S, A>['getState'];
+    readonly setState: Logix.ModuleRuntime<S, A>['setState'];
+    readonly actions$: Logix.ModuleRuntime<S, A>['actions$'];
+    readonly changes: Logix.ModuleRuntime<S, A>['changes'];
+    readonly ref: Logix.ModuleRuntime<S, A>['ref'];
+}
+
+export type { Dispatch as D, ModuleActions as M, ModuleDispatchers as a, ModuleDispatchersOfShape as b, ModuleRef as c };

package/dist/ModuleRef-wZSQ3Wwo.d.ts

@@ -0,0 +1,73 @@
+import * as Logix from '@logixjs/core';
+
+type Dispatch<A> = ((action: A) => void) & {
+    readonly batch: (actions: ReadonlyArray<A>) => void;
+    readonly lowPriority: (action: A) => void;
+};
+type ActionArgs<P> = [P] extends [void] ? [] | [P] : [P];
+type ActionFn<P, Out> = (...args: ActionArgs<P>) => Out;
+type ActionTag<A> = A extends {
+    readonly _tag: infer T;
+} ? T : A extends {
+    readonly type: infer T;
+} ? T : never;
+type ActionTags<A> = Extract<ActionTag<A>, string>;
+type ActionPayload<A, K> = Extract<A, {
+    readonly _tag: K;
+} | {
+    readonly type: K;
+}> extends {
+    readonly payload?: infer P;
+} ? P : never;
+type AnyActionToken = Logix.Action.ActionToken<string, any, any>;
+type ModuleDispatchersOfShape<Sh extends Logix.AnyModuleShape> = Sh['actionMap'];
+type ModuleActions<A, Tags extends string = ActionTags<A>> = {
+    readonly dispatch: Dispatch<A>;
+} & ([ActionTags<A>] extends [never] ? {} : {
+    readonly [K in Tags & ActionTags<A>]: ActionFn<ActionPayload<A, K>, void>;
+});
+type ActionMapOfDef<Def> = Def extends {
+    readonly actions: infer ActionMap;
+} ? ActionMap : never;
+type ModuleDispatchers<A, Tags extends string = ActionTags<A>, Def = unknown> = [ActionMapOfDef<Def>] extends [
+    never
+] ? [ActionTags<A>] extends [never] ? {} : {
+    readonly [K in Tags & ActionTags<A>]: ActionFn<ActionPayload<A, K>, Extract<A, {
+        readonly _tag: K;
+    } | {
+        readonly type: K;
+    }>>;
+} : ActionMapOfDef<Def> extends Record<string, AnyActionToken> ? ActionMapOfDef<Def> : [ActionTags<A>] extends [never] ? {} : {
+    readonly [K in Tags & ActionTags<A>]: ActionFn<ActionPayload<A, K>, Extract<A, {
+        readonly _tag: K;
+    } | {
+        readonly type: K;
+    }>>;
+};
+interface ModuleImports {
+    readonly get: <Id extends string, Sh extends Logix.AnyModuleShape>(module: Logix.ModuleTagType<Id, Sh>) => ModuleRef<Logix.StateOf<Sh>, Logix.ActionOf<Sh>, keyof Sh['actionMap'] & string, Logix.ModuleTagType<Id, Sh>, ModuleDispatchersOfShape<Sh>>;
+}
+interface ModuleRef<S, A, Tags extends string = ActionTags<A>, Def = unknown, Dispatchers = ModuleDispatchers<A, Tags, Def>> {
+    /**
+     * Definition anchor (typically a ModuleTag) for reflecting actions/reducers/source and other metadata.
+     * - DX: when `runtime.actions.*` can't jump to source, use `ref.def?.reducers?.xxx` / `ref.def?.actions.xxx` to locate definitions quickly.
+     */
+    readonly def?: Def;
+    readonly runtime: Logix.ModuleRuntime<S, A>;
+    readonly dispatch: Dispatch<A>;
+    readonly actions: ModuleActions<A, Tags>;
+    readonly dispatchers: Dispatchers;
+    /**
+     * Fractal module imports sugar:
+     * - host.imports.get(ChildModule) resolves a child module instance within the host instance scope.
+     * - strict by default: throws when scope is missing, avoiding accidentally routing to a global instance.
+     */
+    readonly imports: ModuleImports;
+    readonly getState: Logix.ModuleRuntime<S, A>['getState'];
+    readonly setState: Logix.ModuleRuntime<S, A>['setState'];
+    readonly actions$: Logix.ModuleRuntime<S, A>['actions$'];
+    readonly changes: Logix.ModuleRuntime<S, A>['changes'];
+    readonly ref: Logix.ModuleRuntime<S, A>['ref'];
+}
+
+export type { Dispatch as D, ModuleActions as M, ModuleDispatchers as a, ModuleDispatchersOfShape as b, ModuleRef as c };