Compare commits
9 Commits
master
...
11c10f7142
| Author | SHA1 | Date | |
|---|---|---|---|
| 11c10f7142 | |||
|
|
8e81ec85de | ||
|
|
97246845da | ||
|
|
2c78b17f52 | ||
|
|
6c14495693 | ||
|
|
a73da25b8c | ||
|
|
d0bc4e4903 | ||
| 0ae55bd02c | |||
|
|
bb044e766d |
@@ -1,6 +1,6 @@
|
|||||||
# Effect FC Monorepo
|
# Effect FC Monorepo
|
||||||
|
|
||||||
[Effect-TS](https://effect.website/) integration for React 19+ that allows you to write function components using Effect generators.
|
[Effect-TS](https://effect.website/) integration for React 19.2+ that allows you to write function components using Effect generators.
|
||||||
|
|
||||||
This monorepo contains:
|
This monorepo contains:
|
||||||
- [The `effect-fc` library](packages/effect-fc)
|
- [The `effect-fc` library](packages/effect-fc)
|
||||||
|
|||||||
6
bun.lock
6
bun.lock
@@ -6,7 +6,7 @@
|
|||||||
"name": "@effect-fc/monorepo",
|
"name": "@effect-fc/monorepo",
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@biomejs/biome": "^2.3.11",
|
"@biomejs/biome": "^2.3.11",
|
||||||
"@effect/language-service": "^0.72.0",
|
"@effect/language-service": "^0.77.0",
|
||||||
"@types/bun": "^1.3.6",
|
"@types/bun": "^1.3.6",
|
||||||
"npm-check-updates": "^19.3.1",
|
"npm-check-updates": "^19.3.1",
|
||||||
"npm-sort": "^0.0.4",
|
"npm-sort": "^0.0.4",
|
||||||
@@ -16,7 +16,7 @@
|
|||||||
},
|
},
|
||||||
"packages/effect-fc": {
|
"packages/effect-fc": {
|
||||||
"name": "effect-fc",
|
"name": "effect-fc",
|
||||||
"version": "0.2.2",
|
"version": "0.2.3",
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@effect/platform-browser": "^0.74.0",
|
"@effect/platform-browser": "^0.74.0",
|
||||||
},
|
},
|
||||||
@@ -116,7 +116,7 @@
|
|||||||
|
|
||||||
"@effect-fc/example": ["@effect-fc/example@workspace:packages/example"],
|
"@effect-fc/example": ["@effect-fc/example@workspace:packages/example"],
|
||||||
|
|
||||||
"@effect/language-service": ["@effect/language-service@0.72.0", "", { "bin": { "effect-language-service": "cli.js" } }, "sha512-MWkyTPCXSs5Q3OIBWR3q24SA+ipkdWW7EBJBt6EPUzlzZxjJLXtLBhXpMoCFheSEM0FTWOHT4BRLh5lufsmjVw=="],
|
"@effect/language-service": ["@effect/language-service@0.77.0", "", { "bin": { "effect-language-service": "cli.js" } }, "sha512-QP2bri8DdcK7Eo+SqFS2yNeD0Ch9kKHYxq2jeE9CaPpBknevCNFb3+hT6qSsPt2P6yOkhNP83KMy5Uk7DGBXlg=="],
|
||||||
|
|
||||||
"@effect/platform": ["@effect/platform@0.94.2", "", { "dependencies": { "find-my-way-ts": "^0.1.6", "msgpackr": "^1.11.4", "multipasta": "^0.2.7" }, "peerDependencies": { "effect": "^3.19.15" } }, "sha512-85vdwpnK4oH/rJ3EuX/Gi2Hkt+K4HvXWr9bxCuqvty9hxyEcRxkJcqTesYrcVoQB6aULb1Za2B0MKoTbvffB3Q=="],
|
"@effect/platform": ["@effect/platform@0.94.2", "", { "dependencies": { "find-my-way-ts": "^0.1.6", "msgpackr": "^1.11.4", "multipasta": "^0.2.7" }, "peerDependencies": { "effect": "^3.19.15" } }, "sha512-85vdwpnK4oH/rJ3EuX/Gi2Hkt+K4HvXWr9bxCuqvty9hxyEcRxkJcqTesYrcVoQB6aULb1Za2B0MKoTbvffB3Q=="],
|
||||||
|
|
||||||
|
|||||||
@@ -16,7 +16,7 @@
|
|||||||
},
|
},
|
||||||
"devDependencies": {
|
"devDependencies": {
|
||||||
"@biomejs/biome": "^2.3.11",
|
"@biomejs/biome": "^2.3.11",
|
||||||
"@effect/language-service": "^0.72.0",
|
"@effect/language-service": "^0.77.0",
|
||||||
"@types/bun": "^1.3.6",
|
"@types/bun": "^1.3.6",
|
||||||
"npm-check-updates": "^19.3.1",
|
"npm-check-updates": "^19.3.1",
|
||||||
"npm-sort": "^0.0.4",
|
"npm-sort": "^0.0.4",
|
||||||
|
|||||||
@@ -7,29 +7,27 @@ import * as Component from "./Component.js"
|
|||||||
export const TypeId: unique symbol = Symbol.for("@effect-fc/Async/Async")
|
export const TypeId: unique symbol = Symbol.for("@effect-fc/Async/Async")
|
||||||
export type TypeId = typeof TypeId
|
export type TypeId = typeof TypeId
|
||||||
|
|
||||||
export interface Async extends Async.Options {
|
export interface Async extends AsyncOptions {
|
||||||
readonly [TypeId]: TypeId
|
readonly [TypeId]: TypeId
|
||||||
}
|
}
|
||||||
|
|
||||||
export namespace Async {
|
export interface AsyncOptions {
|
||||||
export interface Options {
|
|
||||||
readonly defaultFallback?: React.ReactNode
|
readonly defaultFallback?: React.ReactNode
|
||||||
}
|
}
|
||||||
|
|
||||||
export type Props = Omit<React.SuspenseProps, "children">
|
export type AsyncProps = Omit<React.SuspenseProps, "children">
|
||||||
}
|
|
||||||
|
|
||||||
|
|
||||||
const AsyncProto = Object.freeze({
|
export const AsyncPrototype = Object.freeze({
|
||||||
[TypeId]: TypeId,
|
[TypeId]: TypeId,
|
||||||
|
|
||||||
makeFunctionComponent<P extends {}, A extends React.ReactNode, E, R>(
|
asFunctionComponent<P extends {}, A extends React.ReactNode, E, R>(
|
||||||
this: Component.Component<P, A, E, R> & Async,
|
this: Component.Component<P, A, E, R> & Async,
|
||||||
runtimeRef: React.RefObject<Runtime.Runtime<Exclude<R, Scope.Scope>>>,
|
runtimeRef: React.RefObject<Runtime.Runtime<Exclude<R, Scope.Scope>>>,
|
||||||
) {
|
) {
|
||||||
const SuspenseInner = (props: { readonly promise: Promise<React.ReactNode> }) => React.use(props.promise)
|
const SuspenseInner = (props: { readonly promise: Promise<React.ReactNode> }) => React.use(props.promise)
|
||||||
|
|
||||||
return ({ fallback, name, ...props }: Async.Props) => {
|
return ({ fallback, name, ...props }: AsyncProps) => {
|
||||||
const promise = Runtime.runPromise(runtimeRef.current)(
|
const promise = Runtime.runPromise(runtimeRef.current)(
|
||||||
Effect.andThen(
|
Effect.andThen(
|
||||||
Component.useScope([], this),
|
Component.useScope([], this),
|
||||||
@@ -54,7 +52,7 @@ export const async = <T extends Component.Component<any, any, any, any>>(
|
|||||||
): (
|
): (
|
||||||
& Omit<T, keyof Component.Component.AsComponent<T>>
|
& Omit<T, keyof Component.Component.AsComponent<T>>
|
||||||
& Component.Component<
|
& Component.Component<
|
||||||
Component.Component.Props<T> & Async.Props,
|
Component.Component.Props<T> & AsyncProps,
|
||||||
Component.Component.Success<T>,
|
Component.Component.Success<T>,
|
||||||
Component.Component.Error<T>,
|
Component.Component.Error<T>,
|
||||||
Component.Component.Context<T>
|
Component.Component.Context<T>
|
||||||
@@ -63,22 +61,22 @@ export const async = <T extends Component.Component<any, any, any, any>>(
|
|||||||
) => Object.setPrototypeOf(
|
) => Object.setPrototypeOf(
|
||||||
Object.assign(function() {}, self),
|
Object.assign(function() {}, self),
|
||||||
Object.freeze(Object.setPrototypeOf(
|
Object.freeze(Object.setPrototypeOf(
|
||||||
Object.assign({}, AsyncProto),
|
Object.assign({}, AsyncPrototype),
|
||||||
Object.getPrototypeOf(self),
|
Object.getPrototypeOf(self),
|
||||||
)),
|
)),
|
||||||
)
|
)
|
||||||
|
|
||||||
export const withOptions: {
|
export const withOptions: {
|
||||||
<T extends Component.Component<any, any, any, any> & Async>(
|
<T extends Component.Component<any, any, any, any> & Async>(
|
||||||
options: Partial<Async.Options>
|
options: Partial<AsyncOptions>
|
||||||
): (self: T) => T
|
): (self: T) => T
|
||||||
<T extends Component.Component<any, any, any, any> & Async>(
|
<T extends Component.Component<any, any, any, any> & Async>(
|
||||||
self: T,
|
self: T,
|
||||||
options: Partial<Async.Options>,
|
options: Partial<AsyncOptions>,
|
||||||
): T
|
): T
|
||||||
} = Function.dual(2, <T extends Component.Component<any, any, any, any> & Async>(
|
} = Function.dual(2, <T extends Component.Component<any, any, any, any> & Async>(
|
||||||
self: T,
|
self: T,
|
||||||
options: Partial<Async.Options>,
|
options: Partial<AsyncOptions>,
|
||||||
): T => Object.setPrototypeOf(
|
): T => Object.setPrototypeOf(
|
||||||
Object.assign(function() {}, self, options),
|
Object.assign(function() {}, self, options),
|
||||||
Object.getPrototypeOf(self),
|
Object.getPrototypeOf(self),
|
||||||
|
|||||||
@@ -1,25 +1,17 @@
|
|||||||
/** biome-ignore-all lint/complexity/noBannedTypes: {} is the default type for React props */
|
/** biome-ignore-all lint/complexity/noBannedTypes: {} is the default type for React props */
|
||||||
/** biome-ignore-all lint/complexity/useArrowFunction: necessary for class prototypes */
|
/** biome-ignore-all lint/complexity/useArrowFunction: necessary for class prototypes */
|
||||||
import { Context, type Duration, Effect, Effectable, Equivalence, ExecutionStrategy, Exit, Fiber, Function, HashMap, Layer, ManagedRuntime, Option, Predicate, Ref, Runtime, Scope, Tracer, type Utils } from "effect"
|
import { Context, type Duration, Effect, Equivalence, ExecutionStrategy, Exit, Fiber, Function, HashMap, identity, Layer, ManagedRuntime, Option, Pipeable, Predicate, Ref, Runtime, Scope, Tracer, type Utils } from "effect"
|
||||||
import * as React from "react"
|
import * as React from "react"
|
||||||
import { Memoized } from "./index.js"
|
|
||||||
|
|
||||||
|
|
||||||
export const TypeId: unique symbol = Symbol.for("@effect-fc/Component/Component")
|
export const TypeId: unique symbol = Symbol.for("@effect-fc/Component/Component")
|
||||||
export type TypeId = typeof TypeId
|
export type TypeId = typeof TypeId
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Interface representing an Effect-based React Component.
|
* Represents an Effect-based React Component that integrates the Effect system with React.
|
||||||
*
|
|
||||||
* This is both:
|
|
||||||
* - an Effect that produces a React function component
|
|
||||||
* - a constructor-like object with component metadata and options
|
|
||||||
*/
|
*/
|
||||||
export interface Component<P extends {}, A extends React.ReactNode, E, R>
|
export interface Component<P extends {}, A extends React.ReactNode, E, R>
|
||||||
extends
|
extends ComponentPrototype<P, A, R>, ComponentOptions {
|
||||||
Effect.Effect<(props: P) => A, never, Exclude<R, Scope.Scope>>,
|
|
||||||
Component.Options
|
|
||||||
{
|
|
||||||
new(_: never): Record<string, never>
|
new(_: never): Record<string, never>
|
||||||
readonly [TypeId]: TypeId
|
readonly [TypeId]: TypeId
|
||||||
readonly "~Props": P
|
readonly "~Props": P
|
||||||
@@ -28,11 +20,6 @@ extends
|
|||||||
readonly "~Context": R
|
readonly "~Context": R
|
||||||
|
|
||||||
readonly body: (props: P) => Effect.Effect<A, E, R>
|
readonly body: (props: P) => Effect.Effect<A, E, R>
|
||||||
|
|
||||||
/** @internal */
|
|
||||||
makeFunctionComponent(
|
|
||||||
runtimeRef: React.Ref<Runtime.Runtime<Exclude<R, Scope.Scope>>>
|
|
||||||
): (props: P) => A
|
|
||||||
}
|
}
|
||||||
|
|
||||||
export declare namespace Component {
|
export declare namespace Component {
|
||||||
@@ -42,56 +29,29 @@ export declare namespace Component {
|
|||||||
export type Context<T extends Component<any, any, any, any>> = [T] extends [Component<infer _P, infer _A, infer _E, infer R>] ? R : never
|
export type Context<T extends Component<any, any, any, any>> = [T] extends [Component<infer _P, infer _A, infer _E, infer R>] ? R : never
|
||||||
|
|
||||||
export type AsComponent<T extends Component<any, any, any, any>> = Component<Props<T>, Success<T>, Error<T>, Context<T>>
|
export type AsComponent<T extends Component<any, any, any, any>> = Component<Props<T>, Success<T>, Error<T>, Context<T>>
|
||||||
|
|
||||||
/**
|
|
||||||
* Options that can be set on the component
|
|
||||||
*/
|
|
||||||
export interface Options {
|
|
||||||
/** Custom displayName for React DevTools and debugging. */
|
|
||||||
readonly displayName?: string
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Strategy used when executing finalizers on unmount/scope close.
|
|
||||||
* @default ExecutionStrategy.sequential
|
|
||||||
*/
|
|
||||||
readonly finalizerExecutionStrategy: ExecutionStrategy.ExecutionStrategy
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Debounce time before executing finalizers after component unmount.
|
|
||||||
* Helps avoid unnecessary work during fast remount/remount cycles.
|
|
||||||
* @default "100 millis"
|
|
||||||
*/
|
|
||||||
readonly finalizerExecutionDebounce: Duration.DurationInput
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
const ComponentProto = Object.freeze({
|
export interface ComponentPrototype<P extends {}, A extends React.ReactNode, R>
|
||||||
...Effectable.CommitPrototype,
|
extends Pipeable.Pipeable {
|
||||||
|
readonly [TypeId]: TypeId
|
||||||
|
readonly use: Effect.Effect<(props: P) => A, never, Exclude<R, Scope.Scope>>
|
||||||
|
|
||||||
|
asFunctionComponent(
|
||||||
|
runtimeRef: React.Ref<Runtime.Runtime<Exclude<R, Scope.Scope>>>
|
||||||
|
): (props: P) => A
|
||||||
|
|
||||||
|
setFunctionComponentName(f: React.FC<P>): void
|
||||||
|
transformFunctionComponent(f: React.FC<P>): React.FC<P>
|
||||||
|
}
|
||||||
|
|
||||||
|
export const ComponentPrototype: ComponentPrototype<any, any, any> = Object.freeze({
|
||||||
[TypeId]: TypeId,
|
[TypeId]: TypeId,
|
||||||
|
...Pipeable.Prototype,
|
||||||
|
|
||||||
commit: Effect.fnUntraced(function* <P extends {}, A extends React.ReactNode, E, R>(
|
get use() { return use(this) },
|
||||||
this: Component<P, A, E, R>
|
|
||||||
) {
|
|
||||||
// biome-ignore lint/style/noNonNullAssertion: React ref initialization
|
|
||||||
const runtimeRef = React.useRef<Runtime.Runtime<Exclude<R, Scope.Scope>>>(null!)
|
|
||||||
runtimeRef.current = yield* Effect.runtime<Exclude<R, Scope.Scope>>()
|
|
||||||
|
|
||||||
return yield* React.useState(() => Runtime.runSync(runtimeRef.current)(Effect.cachedFunction(
|
asFunctionComponent<P extends {}, A extends React.ReactNode, E, R>(
|
||||||
(_services: readonly any[]) => Effect.sync(() => {
|
|
||||||
const f: React.FC<P> = this.makeFunctionComponent(runtimeRef)
|
|
||||||
f.displayName = this.displayName ?? "Anonymous"
|
|
||||||
return Memoized.isMemoized(this)
|
|
||||||
? React.memo(f, this.propsAreEqual)
|
|
||||||
: f
|
|
||||||
}),
|
|
||||||
Equivalence.array(Equivalence.strict()),
|
|
||||||
)))[0](Array.from(
|
|
||||||
Context.omit(...nonReactiveTags)(runtimeRef.current.context).unsafeMap.values()
|
|
||||||
))
|
|
||||||
}),
|
|
||||||
|
|
||||||
makeFunctionComponent<P extends {}, A extends React.ReactNode, E, R>(
|
|
||||||
this: Component<P, A, E, R>,
|
this: Component<P, A, E, R>,
|
||||||
runtimeRef: React.RefObject<Runtime.Runtime<Exclude<R, Scope.Scope>>>,
|
runtimeRef: React.RefObject<Runtime.Runtime<Exclude<R, Scope.Scope>>>,
|
||||||
) {
|
) {
|
||||||
@@ -102,14 +62,69 @@ const ComponentProto = Object.freeze({
|
|||||||
)
|
)
|
||||||
)
|
)
|
||||||
},
|
},
|
||||||
|
|
||||||
|
setFunctionComponentName<P extends {}, A extends React.ReactNode, E, R>(
|
||||||
|
this: Component<P, A, E, R>,
|
||||||
|
f: React.FC<P>,
|
||||||
|
) {
|
||||||
|
f.displayName = this.displayName ?? "Anonymous"
|
||||||
|
},
|
||||||
|
|
||||||
|
transformFunctionComponent: identity,
|
||||||
} as const)
|
} as const)
|
||||||
|
|
||||||
const defaultOptions: Component.Options = {
|
const use = Effect.fnUntraced(function* <P extends {}, A extends React.ReactNode, E, R>(
|
||||||
|
self: Component<P, A, E, R>
|
||||||
|
) {
|
||||||
|
// biome-ignore lint/style/noNonNullAssertion: React ref initialization
|
||||||
|
const runtimeRef = React.useRef<Runtime.Runtime<Exclude<R, Scope.Scope>>>(null!)
|
||||||
|
runtimeRef.current = yield* Effect.runtime<Exclude<R, Scope.Scope>>()
|
||||||
|
|
||||||
|
return yield* React.useState(() => Runtime.runSync(runtimeRef.current)(Effect.cachedFunction(
|
||||||
|
(_services: readonly any[]) => Effect.sync(() => {
|
||||||
|
const f: React.FC<P> = self.asFunctionComponent(runtimeRef)
|
||||||
|
self.setFunctionComponentName(f)
|
||||||
|
return self.transformFunctionComponent(f)
|
||||||
|
}),
|
||||||
|
Equivalence.array(Equivalence.strict()),
|
||||||
|
)))[0](Array.from(
|
||||||
|
Context.omit(...nonReactiveTags)(runtimeRef.current.context).unsafeMap.values()
|
||||||
|
))
|
||||||
|
})
|
||||||
|
|
||||||
|
|
||||||
|
export interface ComponentOptions {
|
||||||
|
/**
|
||||||
|
* Custom display name for the component in React DevTools and debugging utilities.
|
||||||
|
* Improves developer experience by providing meaningful component identification.
|
||||||
|
*/
|
||||||
|
readonly displayName?: string
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Specifies the execution strategy for finalizers when the component unmounts or its scope closes.
|
||||||
|
* Determines whether finalizers execute sequentially or in parallel.
|
||||||
|
*
|
||||||
|
* @default ExecutionStrategy.sequential
|
||||||
|
*/
|
||||||
|
readonly finalizerExecutionStrategy: ExecutionStrategy.ExecutionStrategy
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Debounce duration before executing finalizers after component unmount.
|
||||||
|
* Prevents unnecessary cleanup work during rapid remount/unmount cycles,
|
||||||
|
* which is common in development and certain UI patterns.
|
||||||
|
*
|
||||||
|
* @default "100 millis"
|
||||||
|
*/
|
||||||
|
readonly finalizerExecutionDebounce: Duration.DurationInput
|
||||||
|
}
|
||||||
|
|
||||||
|
export const defaultOptions: ComponentOptions = {
|
||||||
finalizerExecutionStrategy: ExecutionStrategy.sequential,
|
finalizerExecutionStrategy: ExecutionStrategy.sequential,
|
||||||
finalizerExecutionDebounce: "100 millis",
|
finalizerExecutionDebounce: "100 millis",
|
||||||
}
|
}
|
||||||
|
|
||||||
const nonReactiveTags = [Tracer.ParentSpan] as const
|
|
||||||
|
export const nonReactiveTags = [Tracer.ParentSpan] as const
|
||||||
|
|
||||||
|
|
||||||
export const isComponent = (u: unknown): u is Component<{}, React.ReactNode, unknown, unknown> => Predicate.hasProperty(u, TypeId)
|
export const isComponent = (u: unknown): u is Component<{}, React.ReactNode, unknown, unknown> => Predicate.hasProperty(u, TypeId)
|
||||||
@@ -340,17 +355,51 @@ export declare namespace make {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Creates an Effect-FC Component following the same overloads and pipeline style as `Effect.fn`.
|
* Creates an Effect-FC Component using the same overloads and pipeline composition style as `Effect.fn`.
|
||||||
*
|
*
|
||||||
* This is the **recommended** way to define components. It supports:
|
* This is the **recommended** approach for defining Effect-FC components. It provides comprehensive
|
||||||
* - Generator syntax (yield* style) — most ergonomic and readable
|
* support for multiple component definition patterns:
|
||||||
* - Direct Effect return (non-generator)
|
|
||||||
* - Chained transformation functions (like Effect.fn pipelines)
|
|
||||||
* - Optional tracing span with automatic `displayName`
|
|
||||||
*
|
*
|
||||||
* When you provide a `spanName` as the first argument, two things happen automatically:
|
* - **Generator syntax** (yield* style): Most ergonomic and readable approach for sequential operations
|
||||||
* 1. A tracing span is created with that name (unless using `makeUntraced`)
|
* - **Direct Effect return**: For simple components that return an Effect directly
|
||||||
* 2. The resulting React component gets `displayName = spanName`
|
* - **Chained transformation functions**: Enables Effect.fn-style pipelines for composable transformations
|
||||||
|
* - **Automatic tracing**: Optional tracing span creation with automatic `displayName` assignment
|
||||||
|
*
|
||||||
|
* When a `spanName` string is provided, the following occurs automatically:
|
||||||
|
* 1. A distributed tracing span is created with the specified name
|
||||||
|
* 2. The resulting React component receives `displayName = spanName` for DevTools visibility
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make("MyComponent")(function* (props: { count: number }) {
|
||||||
|
* const value = yield* someEffect
|
||||||
|
* return <div>{value}</div>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
|
*
|
||||||
|
* @example As an opaque type using class syntax
|
||||||
|
* ```tsx
|
||||||
|
* class MyComponent extends Component.make("MyComponent")(function* (props: { count: number }) {
|
||||||
|
* const value = yield* someEffect
|
||||||
|
* return <div>{value}</div>
|
||||||
|
* }) {}
|
||||||
|
* ```
|
||||||
|
*
|
||||||
|
* @example Without name
|
||||||
|
* ```tsx
|
||||||
|
* class MyComponent extends Component.make(function* (props: { count: number }) {
|
||||||
|
* const value = yield* someEffect
|
||||||
|
* return <div>{value}</div>
|
||||||
|
* }) {}
|
||||||
|
* ```
|
||||||
|
*
|
||||||
|
* @example Using pipeline
|
||||||
|
* ```tsx
|
||||||
|
* class MyComponent extends Component.make("MyComponent")(
|
||||||
|
* (props: { count: number }) => someEffect,
|
||||||
|
* Effect.map(value => <div>{value}</div>),
|
||||||
|
* ) {}
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const make: (
|
export const make: (
|
||||||
& make.Gen
|
& make.Gen
|
||||||
@@ -365,7 +414,7 @@ export const make: (
|
|||||||
Object.assign(function() {}, defaultOptions, {
|
Object.assign(function() {}, defaultOptions, {
|
||||||
body: Effect.fn(spanNameOrBody as any, ...pipeables),
|
body: Effect.fn(spanNameOrBody as any, ...pipeables),
|
||||||
}),
|
}),
|
||||||
ComponentProto,
|
ComponentPrototype,
|
||||||
)
|
)
|
||||||
}
|
}
|
||||||
else {
|
else {
|
||||||
@@ -375,21 +424,56 @@ export const make: (
|
|||||||
body: Effect.fn(spanNameOrBody, spanOptions)(body, ...pipeables as []),
|
body: Effect.fn(spanNameOrBody, spanOptions)(body, ...pipeables as []),
|
||||||
displayName: spanNameOrBody,
|
displayName: spanNameOrBody,
|
||||||
}),
|
}),
|
||||||
ComponentProto,
|
ComponentPrototype,
|
||||||
)
|
)
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Same as `make`, but creates an **untraced** version — no automatic tracing span is created.
|
* Creates an Effect-FC Component without automatic distributed tracing.
|
||||||
*
|
*
|
||||||
* Follows the exact same API shape as `Effect.fnUntraced`.
|
* This function provides the same API surface as `make`, but does not create automatic tracing spans.
|
||||||
* Useful for:
|
* It follows the exact same overload structure as `Effect.fnUntraced`.
|
||||||
* - Components where you want full manual control over tracing
|
|
||||||
* - Avoiding span noise in deeply nested UI
|
|
||||||
*
|
*
|
||||||
* When a string is provided as first argument, it is **only** used as the React component's `displayName`
|
* Use this variant when you need:
|
||||||
* (no tracing span is created).
|
* - Full manual control over tracing instrumentation
|
||||||
|
* - To reduce tracing overhead in deeply nested component hierarchies
|
||||||
|
* - To avoid span noise in performance-sensitive applications
|
||||||
|
*
|
||||||
|
* When a `spanName` string is provided, it is used **exclusively** as the React component's
|
||||||
|
* `displayName` for DevTools identification. No tracing span is created.
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.makeUntraced("MyComponent")(function* (props: { count: number }) {
|
||||||
|
* const value = yield* someEffect
|
||||||
|
* return <div>{value}</div>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
|
*
|
||||||
|
* @example As an opaque type using class syntax
|
||||||
|
* ```tsx
|
||||||
|
* class MyComponent extends Component.makeUntraced("MyComponent")(function* (props: { count: number }) {
|
||||||
|
* const value = yield* someEffect
|
||||||
|
* return <div>{value}</div>
|
||||||
|
* }) {}
|
||||||
|
* ```
|
||||||
|
*
|
||||||
|
* @example Without name
|
||||||
|
* ```tsx
|
||||||
|
* class MyComponent extends Component.makeUntraced(function* (props: { count: number }) {
|
||||||
|
* const value = yield* someEffect
|
||||||
|
* return <div>{value}</div>
|
||||||
|
* }) {}
|
||||||
|
* ```
|
||||||
|
*
|
||||||
|
* @example Using pipeline
|
||||||
|
* ```tsx
|
||||||
|
* class MyComponent extends Component.makeUntraced("MyComponent")(
|
||||||
|
* (props: { count: number }) => someEffect,
|
||||||
|
* Effect.map(value => <div>{value}</div>),
|
||||||
|
* ) {}
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const makeUntraced: (
|
export const makeUntraced: (
|
||||||
& make.Gen
|
& make.Gen
|
||||||
@@ -401,52 +485,71 @@ export const makeUntraced: (
|
|||||||
Object.assign(function() {}, defaultOptions, {
|
Object.assign(function() {}, defaultOptions, {
|
||||||
body: Effect.fnUntraced(spanNameOrBody as any, ...pipeables as []),
|
body: Effect.fnUntraced(spanNameOrBody as any, ...pipeables as []),
|
||||||
}),
|
}),
|
||||||
ComponentProto,
|
ComponentPrototype,
|
||||||
)
|
)
|
||||||
: (body: any, ...pipeables: any[]) => Object.setPrototypeOf(
|
: (body: any, ...pipeables: any[]) => Object.setPrototypeOf(
|
||||||
Object.assign(function() {}, defaultOptions, {
|
Object.assign(function() {}, defaultOptions, {
|
||||||
body: Effect.fnUntraced(body, ...pipeables as []),
|
body: Effect.fnUntraced(body, ...pipeables as []),
|
||||||
displayName: spanNameOrBody,
|
displayName: spanNameOrBody,
|
||||||
}),
|
}),
|
||||||
ComponentProto,
|
ComponentPrototype,
|
||||||
)
|
)
|
||||||
)
|
)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Creates a new component with modified options while preserving original behavior.
|
* Creates a new component with modified configuration options while preserving all original behavior.
|
||||||
|
*
|
||||||
|
* This function allows you to customize component-level options such as finalizer execution strategy
|
||||||
|
* and debounce timing.
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponentWithCustomOptions = MyComponent.pipe(
|
||||||
|
* Component.withOptions({
|
||||||
|
* finalizerExecutionStrategy: ExecutionStrategy.parallel,
|
||||||
|
* finalizerExecutionDebounce: "50 millis"
|
||||||
|
* })
|
||||||
|
* )
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const withOptions: {
|
export const withOptions: {
|
||||||
<T extends Component<any, any, any, any>>(
|
<T extends Component<any, any, any, any>>(
|
||||||
options: Partial<Component.Options>
|
options: Partial<ComponentOptions>
|
||||||
): (self: T) => T
|
): (self: T) => T
|
||||||
<T extends Component<any, any, any, any>>(
|
<T extends Component<any, any, any, any>>(
|
||||||
self: T,
|
self: T,
|
||||||
options: Partial<Component.Options>,
|
options: Partial<ComponentOptions>,
|
||||||
): T
|
): T
|
||||||
} = Function.dual(2, <T extends Component<any, any, any, any>>(
|
} = Function.dual(2, <T extends Component<any, any, any, any>>(
|
||||||
self: T,
|
self: T,
|
||||||
options: Partial<Component.Options>,
|
options: Partial<ComponentOptions>,
|
||||||
): T => Object.setPrototypeOf(
|
): T => Object.setPrototypeOf(
|
||||||
Object.assign(function() {}, self, options),
|
Object.assign(function() {}, self, options),
|
||||||
Object.getPrototypeOf(self),
|
Object.getPrototypeOf(self),
|
||||||
))
|
))
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Wraps an Effect-FC `Component` and turns it into a regular React function component
|
* Wraps an Effect-FC Component and converts it into a standard React function component,
|
||||||
* that serves as an **entrypoint** into an Effect-FC component hierarchy.
|
* serving as an **entrypoint** into an Effect-FC component hierarchy.
|
||||||
*
|
*
|
||||||
* This is the recommended way to connect Effect-FC components to the rest of your React app,
|
* This is how Effect-FC components are integrated with the broader React ecosystem,
|
||||||
* especially when using routers (TanStack Router, React Router, etc.), lazy-loaded routes,
|
* particularly when:
|
||||||
* or any place where a standard React component is expected.
|
* - Using client-side routers (TanStack Router, React Router, etc.)
|
||||||
|
* - Implementing lazy-loaded or code-split routes
|
||||||
|
* - Connecting to third-party libraries expecting standard React components
|
||||||
|
* - Creating component boundaries between Effect-FC and non-Effect-FC code
|
||||||
*
|
*
|
||||||
* The runtime is obtained from the provided React Context, allowing you to:
|
* The Effect runtime is obtained from the provided React Context.
|
||||||
* - Provide dependencies once at a high level
|
|
||||||
* - Use the same runtime across an entire route tree or feature
|
|
||||||
*
|
*
|
||||||
* @example Using TanStack Router
|
* @param self - The Effect-FC Component to be rendered as a standard React component
|
||||||
|
* @param context - React Context providing the Effect Runtime for this component tree.
|
||||||
|
* Create this using the `ReactRuntime` module.
|
||||||
|
*
|
||||||
|
* @example Integration with TanStack Router
|
||||||
* ```tsx
|
* ```tsx
|
||||||
* // Main
|
* // Application root
|
||||||
* export const runtime = ReactRuntime.make(Layer.empty)
|
* export const runtime = ReactRuntime.make(Layer.empty)
|
||||||
|
*
|
||||||
* function App() {
|
* function App() {
|
||||||
* return (
|
* return (
|
||||||
* <ReactRuntime.Provider runtime={runtime}>
|
* <ReactRuntime.Provider runtime={runtime}>
|
||||||
@@ -455,14 +558,12 @@ export const withOptions: {
|
|||||||
* )
|
* )
|
||||||
* }
|
* }
|
||||||
*
|
*
|
||||||
* // Route
|
* // Route definition
|
||||||
* export const Route = createFileRoute("/")({
|
* export const Route = createFileRoute("/")({
|
||||||
* component: Component.withRuntime(HomePage, runtime.context)
|
* component: Component.withRuntime(HomePage, runtime.context)
|
||||||
* })
|
* })
|
||||||
* ```
|
* ```
|
||||||
*
|
*
|
||||||
* @param self - The Effect-FC Component you want to render as a regular React component.
|
|
||||||
* @param context - React Context that holds the Runtime to use for this component tree. See the `ReactRuntime` module to create one.
|
|
||||||
*/
|
*/
|
||||||
export const withRuntime: {
|
export const withRuntime: {
|
||||||
<P extends {}, A extends React.ReactNode, E, R>(
|
<P extends {}, A extends React.ReactNode, E, R>(
|
||||||
@@ -477,15 +578,17 @@ export const withRuntime: {
|
|||||||
context: React.Context<Runtime.Runtime<R>>,
|
context: React.Context<Runtime.Runtime<R>>,
|
||||||
) => function WithRuntime(props: P) {
|
) => function WithRuntime(props: P) {
|
||||||
return React.createElement(
|
return React.createElement(
|
||||||
Runtime.runSync(React.useContext(context))(self),
|
Runtime.runSync(React.useContext(context))(self.use),
|
||||||
props,
|
props,
|
||||||
)
|
)
|
||||||
})
|
})
|
||||||
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Service that keeps track of scopes associated with React components
|
* Internal Effect service that maintains a registry of scopes associated with React component instances.
|
||||||
* (used internally by the `useScope` hook).
|
*
|
||||||
|
* This service is used internally by the `useScope` hook to manage the lifecycle of component scopes,
|
||||||
|
* including tracking active scopes and coordinating their cleanup when components unmount or dependencies change.
|
||||||
*/
|
*/
|
||||||
export class ScopeMap extends Effect.Service<ScopeMap>()("@effect-fc/Component/ScopeMap", {
|
export class ScopeMap extends Effect.Service<ScopeMap>()("@effect-fc/Component/ScopeMap", {
|
||||||
effect: Effect.bind(Effect.Do, "ref", () => Ref.make(HashMap.empty<object, ScopeMap.Entry>()))
|
effect: Effect.bind(Effect.Do, "ref", () => Ref.make(HashMap.empty<object, ScopeMap.Entry>()))
|
||||||
@@ -507,12 +610,21 @@ export declare namespace useScope {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Hook that creates and manages a `Scope` for the current component instance.
|
* Effect hook that creates and manages a `Scope` for the current component instance.
|
||||||
*
|
*
|
||||||
* Automatically closes the scope whenever `deps` changes or the component unmounts.
|
* This hook establishes a new scope that is automatically closed when:
|
||||||
|
* - The component unmounts
|
||||||
|
* - The dependency array `deps` changes
|
||||||
*
|
*
|
||||||
* @param deps - dependency array like in `React.useEffect`
|
* The scope provides a resource management boundary for any Effects executed within the component,
|
||||||
* @param options - finalizer execution control
|
* ensuring proper cleanup of resources and execution of finalizers.
|
||||||
|
*
|
||||||
|
* @param deps - Dependency array following React.useEffect semantics. The scope is recreated
|
||||||
|
* whenever any dependency changes.
|
||||||
|
* @param options - Configuration for finalizer execution behavior, including execution strategy
|
||||||
|
* and debounce timing.
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces a `Scope` for resource management
|
||||||
*/
|
*/
|
||||||
export const useScope = Effect.fnUntraced(function*(
|
export const useScope = Effect.fnUntraced(function*(
|
||||||
deps: React.DependencyList,
|
deps: React.DependencyList,
|
||||||
@@ -567,7 +679,23 @@ export const useScope = Effect.fnUntraced(function*(
|
|||||||
})
|
})
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Runs an effect and returns its result only once on component mount.
|
* Effect hook that executes an Effect once when the component mounts and caches the result.
|
||||||
|
*
|
||||||
|
* This hook is useful for one-time initialization logic that should not be re-executed
|
||||||
|
* when the component re-renders. The Effect is executed exactly once during the component's
|
||||||
|
* initial mount, and the cached result is returned on all subsequent renders.
|
||||||
|
*
|
||||||
|
* @param f - A function that returns the Effect to execute on mount
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces the cached result of the Effect
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make(function*() {
|
||||||
|
* const initialData = yield* Component.useOnMount(() => getData)
|
||||||
|
* return <div>{initialData}</div>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const useOnMount = Effect.fnUntraced(function* <A, E, R>(
|
export const useOnMount = Effect.fnUntraced(function* <A, E, R>(
|
||||||
f: () => Effect.Effect<A, E, R>
|
f: () => Effect.Effect<A, E, R>
|
||||||
@@ -581,9 +709,33 @@ export declare namespace useOnChange {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Runs an effect and returns its result whenever dependencies change.
|
* Effect hook that executes an Effect whenever dependencies change and caches the result.
|
||||||
*
|
*
|
||||||
* Provides its own `Scope` which closes whenever `deps` changes or the component unmounts.
|
* This hook combines the dependency-tracking behavior of React.useEffect with Effect caching.
|
||||||
|
* The Effect is re-executed whenever any dependency in the `deps` array changes, and the result
|
||||||
|
* is cached until the next dependency change.
|
||||||
|
*
|
||||||
|
* A dedicated scope is created for each dependency change, ensuring proper resource cleanup:
|
||||||
|
* - The scope closes when dependencies change
|
||||||
|
* - The scope closes when the component unmounts
|
||||||
|
* - All finalizers are executed according to the configured execution strategy
|
||||||
|
*
|
||||||
|
* @param f - A function that returns the Effect to execute
|
||||||
|
* @param deps - Dependency array following React.useEffect semantics
|
||||||
|
* @param options - Configuration for scope and finalizer behavior
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces the cached result of the Effect
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make(function* (props: { userId: string }) {
|
||||||
|
* const userData = yield* Component.useOnChange(
|
||||||
|
* getUser(props.userId),
|
||||||
|
* [props.userId],
|
||||||
|
* )
|
||||||
|
* return <div>{userData.name}</div>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const useOnChange = Effect.fnUntraced(function* <A, E, R>(
|
export const useOnChange = Effect.fnUntraced(function* <A, E, R>(
|
||||||
f: () => Effect.Effect<A, E, R>,
|
f: () => Effect.Effect<A, E, R>,
|
||||||
@@ -607,9 +759,36 @@ export declare namespace useReactEffect {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Like `React.useEffect` but accepts an effect.
|
* Effect hook that provides Effect-based semantics for React.useEffect.
|
||||||
*
|
*
|
||||||
* Cleanup logic is handled through the `Scope` API rather than using imperative cleanup.
|
* This hook bridges React's useEffect with the Effect system, allowing you to use Effects
|
||||||
|
* for React side effects while maintaining React's dependency tracking and lifecycle semantics.
|
||||||
|
*
|
||||||
|
* Unlike React.useEffect which uses imperative cleanup functions, this hook leverages the
|
||||||
|
* Effect Scope API for resource management. Cleanup logic is expressed declaratively through
|
||||||
|
* finalizers registered with the scope, providing better composability and error handling.
|
||||||
|
*
|
||||||
|
* @param f - A function that returns an Effect to execute as a side effect
|
||||||
|
* @param deps - Optional dependency array following React.useEffect semantics.
|
||||||
|
* If omitted, the effect runs after every render.
|
||||||
|
* @param options - Configuration for finalizer execution mode (sync or fork) and strategy
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces void
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make(function* (props: { id: string }) {
|
||||||
|
* yield* Component.useReactEffect(
|
||||||
|
* () => getNotificationStreamForUser(props.id).pipe(
|
||||||
|
* Stream.unwrap,
|
||||||
|
* Stream.runForEach(notification => Console.log(`Notification received: ${ notification }`),
|
||||||
|
* Effect.forkScoped,
|
||||||
|
* ),
|
||||||
|
* [props.id],
|
||||||
|
* )
|
||||||
|
* return <div>Subscribed to notifications for {props.id}</div>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const useReactEffect = Effect.fnUntraced(function* <E, R>(
|
export const useReactEffect = Effect.fnUntraced(function* <E, R>(
|
||||||
f: () => Effect.Effect<void, E, R>,
|
f: () => Effect.Effect<void, E, R>,
|
||||||
@@ -648,9 +827,43 @@ export declare namespace useReactLayoutEffect {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Like `React.useReactLayoutEffect` but accepts an effect.
|
* Effect hook that provides Effect-based semantics for React.useLayoutEffect.
|
||||||
*
|
*
|
||||||
* Cleanup logic is handled through the `Scope` API rather than using imperative cleanup.
|
* This hook is identical to `useReactEffect` but executes synchronously after DOM mutations
|
||||||
|
* but before the browser paints, following React.useLayoutEffect semantics.
|
||||||
|
*
|
||||||
|
* Use this hook when you need to:
|
||||||
|
* - Measure DOM elements (e.g., for layout calculations)
|
||||||
|
* - Synchronously update state based on DOM measurements
|
||||||
|
* - Avoid visual flicker from asynchronous updates
|
||||||
|
*
|
||||||
|
* Like `useReactEffect`, cleanup logic is handled through the Effect Scope API rather than
|
||||||
|
* imperative cleanup functions, providing declarative and composable resource management.
|
||||||
|
*
|
||||||
|
* @param f - A function that returns an Effect to execute as a layout side effect
|
||||||
|
* @param deps - Optional dependency array following React.useLayoutEffect semantics.
|
||||||
|
* If omitted, the effect runs after every render.
|
||||||
|
* @param options - Configuration for finalizer execution mode (sync or fork) and strategy
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces void
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make(function*() {
|
||||||
|
* const ref = React.useRef<HTMLDivElement>(null)
|
||||||
|
* yield* Component.useReactLayoutEffect(
|
||||||
|
* () => Effect.gen(function* () {
|
||||||
|
* const element = ref.current
|
||||||
|
* if (element) {
|
||||||
|
* const rect = element.getBoundingClientRect()
|
||||||
|
* yield* Console.log(`Element dimensions: ${ rect.width }x${ rect.height }`)
|
||||||
|
* }
|
||||||
|
* }),
|
||||||
|
* [],
|
||||||
|
* )
|
||||||
|
* return <div ref={ref}>Content</div>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const useReactLayoutEffect = Effect.fnUntraced(function* <E, R>(
|
export const useReactLayoutEffect = Effect.fnUntraced(function* <E, R>(
|
||||||
f: () => Effect.Effect<void, E, R>,
|
f: () => Effect.Effect<void, E, R>,
|
||||||
@@ -663,7 +876,23 @@ export const useReactLayoutEffect = Effect.fnUntraced(function* <E, R>(
|
|||||||
})
|
})
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Get a synchronous run function for the current runtime context.
|
* Effect hook that provides a synchronous function to execute Effects within the current runtime context.
|
||||||
|
*
|
||||||
|
* This hook returns a function that can execute Effects synchronously, blocking until completion.
|
||||||
|
* Use this when you need to run Effects from non-Effect code (e.g., event handlers, callbacks)
|
||||||
|
* within a component.
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces a function capable of synchronously executing Effects
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make(function*() {
|
||||||
|
* const runSync = yield* Component.useRunSync<SomeService>() // Specify required services
|
||||||
|
* const runSync = yield* Component.useRunSync() // Or no service requirements
|
||||||
|
*
|
||||||
|
* return <button onClick={() => runSync(someEffect)}>Click me</button>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const useRunSync = <R = never>(): Effect.Effect<
|
export const useRunSync = <R = never>(): Effect.Effect<
|
||||||
<A, E = never>(effect: Effect.Effect<A, E, Scope.Scope | R>) => A,
|
<A, E = never>(effect: Effect.Effect<A, E, Scope.Scope | R>) => A,
|
||||||
@@ -672,7 +901,23 @@ export const useRunSync = <R = never>(): Effect.Effect<
|
|||||||
> => Effect.andThen(Effect.runtime(), Runtime.runSync)
|
> => Effect.andThen(Effect.runtime(), Runtime.runSync)
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Get a Promise-based run function for the current runtime context.
|
* Effect hook that provides an asynchronous function to execute Effects within the current runtime context.
|
||||||
|
*
|
||||||
|
* This hook returns a function that executes Effects asynchronously, returning a Promise that resolves
|
||||||
|
* with the Effect's result. Use this when you need to run Effects from non-Effect code (e.g., event handlers,
|
||||||
|
* async callbacks) and want to handle the result asynchronously.
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces a function capable of asynchronously executing Effects
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make(function*() {
|
||||||
|
* const runPromise = yield* Component.useRunPromise<SomeService>() // Specify required services
|
||||||
|
* const runPromise = yield* Component.useRunPromise() // Or no service requirements
|
||||||
|
*
|
||||||
|
* return <button onClick={() => runPromise(someEffect)}>Click me</button>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const useRunPromise = <R = never>(): Effect.Effect<
|
export const useRunPromise = <R = never>(): Effect.Effect<
|
||||||
<A, E = never>(effect: Effect.Effect<A, E, Scope.Scope | R>) => Promise<A>,
|
<A, E = never>(effect: Effect.Effect<A, E, Scope.Scope | R>) => Promise<A>,
|
||||||
@@ -681,7 +926,32 @@ export const useRunPromise = <R = never>(): Effect.Effect<
|
|||||||
> => Effect.andThen(Effect.runtime(), context => Runtime.runPromise(context))
|
> => Effect.andThen(Effect.runtime(), context => Runtime.runPromise(context))
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Turns a function returning an effect into a memoized synchronous function.
|
* Effect hook that memoizes a function that returns an Effect, providing synchronous execution.
|
||||||
|
*
|
||||||
|
* This hook wraps a function that returns an Effect and returns a memoized version that:
|
||||||
|
* - Executes the Effect synchronously when called
|
||||||
|
* - Is memoized based on the provided dependency array
|
||||||
|
* - Maintains referential equality across renders when dependencies don't change
|
||||||
|
*
|
||||||
|
* Use this to create stable callback references for event handlers and other scenarios
|
||||||
|
* where you need to execute Effects synchronously from non-Effect code.
|
||||||
|
*
|
||||||
|
* @param f - A function that accepts arguments and returns an Effect
|
||||||
|
* @param deps - Dependency array. The memoized function is recreated when dependencies change.
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces a memoized function with the same signature as `f`
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make(function* (props: { onSave: (data: Data) => void }) {
|
||||||
|
* const handleSave = yield* Component.useCallbackSync(
|
||||||
|
* (data: Data) => Effect.sync(() => props.onSave(data)),
|
||||||
|
* [props.onSave],
|
||||||
|
* )
|
||||||
|
*
|
||||||
|
* return <button onClick={() => handleSave(myData)}>Save</button>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const useCallbackSync = Effect.fnUntraced(function* <Args extends unknown[], A, E, R>(
|
export const useCallbackSync = Effect.fnUntraced(function* <Args extends unknown[], A, E, R>(
|
||||||
f: (...args: Args) => Effect.Effect<A, E, R>,
|
f: (...args: Args) => Effect.Effect<A, E, R>,
|
||||||
@@ -696,7 +966,32 @@ export const useCallbackSync = Effect.fnUntraced(function* <Args extends unknown
|
|||||||
})
|
})
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Turns a function returning an effect into a memoized Promise-based asynchronous function.
|
* Effect hook that memoizes a function that returns an Effect, providing asynchronous execution.
|
||||||
|
*
|
||||||
|
* This hook wraps a function that returns an Effect and returns a memoized version that:
|
||||||
|
* - Executes the Effect asynchronously when called, returning a Promise
|
||||||
|
* - Is memoized based on the provided dependency array
|
||||||
|
* - Maintains referential equality across renders when dependencies don't change
|
||||||
|
*
|
||||||
|
* Use this to create stable callback references for async event handlers and other scenarios
|
||||||
|
* where you need to execute Effects asynchronously from non-Effect code.
|
||||||
|
*
|
||||||
|
* @param f - A function that accepts arguments and returns an Effect
|
||||||
|
* @param deps - Dependency array. The memoized function is recreated when dependencies change.
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces a memoized function that returns a Promise
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make(function* (props: { onSave: (data: Data) => void }) {
|
||||||
|
* const handleSave = yield* Component.useCallbackPromise(
|
||||||
|
* (data: Data) => Effect.promise(() => props.onSave(data)),
|
||||||
|
* [props.onSave],
|
||||||
|
* )
|
||||||
|
*
|
||||||
|
* return <button onClick={() => handleSave(myData)}>Save</button>
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
*/
|
*/
|
||||||
export const useCallbackPromise = Effect.fnUntraced(function* <Args extends unknown[], A, E, R>(
|
export const useCallbackPromise = Effect.fnUntraced(function* <Args extends unknown[], A, E, R>(
|
||||||
f: (...args: Args) => Effect.Effect<A, E, R>,
|
f: (...args: Args) => Effect.Effect<A, E, R>,
|
||||||
@@ -715,16 +1010,70 @@ export declare namespace useContext {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Hook that constructs a layer and returns the created context.
|
* Effect hook that constructs an Effect Layer and returns the resulting context.
|
||||||
*
|
*
|
||||||
* The layer gets reconstructed everytime `layer` changes, so make sure its value is stable.
|
* This hook creates a managed runtime from the provided layer and returns the context it produces.
|
||||||
|
* The layer is reconstructed whenever its value changes, so ensure the layer reference is stable
|
||||||
|
* (typically by memoizing it or defining it outside the component).
|
||||||
*
|
*
|
||||||
* Building a layer containing asynchronous effects require the component calling this hook to be made async using `Async.async`.
|
* The hook automatically manages the layer's lifecycle:
|
||||||
|
* - The layer is built when the component mounts or when the layer reference changes
|
||||||
|
* - Resources are properly released when the component unmounts or dependencies change
|
||||||
|
* - Finalizers are executed according to the configured execution strategy
|
||||||
|
*
|
||||||
|
* @param layer - The Effect Layer to construct. Should be a stable reference to avoid unnecessary
|
||||||
|
* reconstruction. Consider memoizing with React.useMemo if defined inline.
|
||||||
|
* @param options - Configuration for scope and finalizer behavior
|
||||||
|
*
|
||||||
|
* @returns An Effect that produces the context created by the layer
|
||||||
|
*
|
||||||
|
* @throws If the layer contains asynchronous effects, the component must be wrapped with `Async.async`
|
||||||
|
*
|
||||||
|
* @example
|
||||||
|
* ```tsx
|
||||||
|
* const MyLayer = Layer.succeed(MyService, new MyServiceImpl())
|
||||||
|
* const MyComponent = Component.make(function*() {
|
||||||
|
* const context = yield* Component.useContextFromLayer(MyLayer)
|
||||||
|
* const Sub = yield* SubComponent.use.pipe(
|
||||||
|
* Effect.provide(context)
|
||||||
|
* )
|
||||||
|
*
|
||||||
|
* return <Sub />
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
|
*
|
||||||
|
* @example With memoized layer
|
||||||
|
* ```tsx
|
||||||
|
* const MyComponent = Component.make(function*(props: { id: string })) {
|
||||||
|
* const context = yield* Component.useContextFromLayer(
|
||||||
|
* React.useMemo(() => Layer.succeed(MyService, new MyServiceImpl(props.id)), [props.id])
|
||||||
|
* )
|
||||||
|
* const Sub = yield* SubComponent.use.pipe(
|
||||||
|
* Effect.provide(context)
|
||||||
|
* )
|
||||||
|
*
|
||||||
|
* return <Sub />
|
||||||
|
* })
|
||||||
|
* ```
|
||||||
|
*
|
||||||
|
* @example With async layer
|
||||||
|
* ```tsx
|
||||||
|
* const MyAsyncLayer = Layer.effect(MyService, someAsyncEffect)
|
||||||
|
* const MyComponent = Component.make(function*() {
|
||||||
|
* const context = yield* Component.useContextFromLayer(MyAsyncLayer)
|
||||||
|
* const Sub = yield* SubComponent.use.pipe(
|
||||||
|
* Effect.provide(context)
|
||||||
|
* )
|
||||||
|
*
|
||||||
|
* return <Sub />
|
||||||
|
* }).pipe(
|
||||||
|
* Async.async // Required to handle async layer effects
|
||||||
|
* )
|
||||||
*/
|
*/
|
||||||
export const useContext = <ROut, E, RIn>(
|
export const useContextFromLayer = <ROut, E, RIn>(
|
||||||
layer: Layer.Layer<ROut, E, RIn>,
|
layer: Layer.Layer<ROut, E, RIn>,
|
||||||
options?: useContext.Options,
|
options?: useContext.Options,
|
||||||
): Effect.Effect<Context.Context<ROut>, E, Exclude<RIn, Scope.Scope>> => useOnChange(() => Effect.context<RIn>().pipe(
|
): Effect.Effect<Context.Context<ROut>, E, RIn | Scope.Scope> => useOnChange(() => Effect.context<RIn>().pipe(
|
||||||
Effect.map(context => ManagedRuntime.make(Layer.provide(layer, Layer.succeedContext(context)))),
|
Effect.map(context => ManagedRuntime.make(Layer.provide(layer, Layer.succeedContext(context)))),
|
||||||
Effect.tap(runtime => Effect.addFinalizer(() => runtime.disposeEffect)),
|
Effect.tap(runtime => Effect.addFinalizer(() => runtime.disposeEffect)),
|
||||||
Effect.andThen(runtime => runtime.runtimeEffect),
|
Effect.andThen(runtime => runtime.runtimeEffect),
|
||||||
|
|||||||
@@ -1,24 +1,30 @@
|
|||||||
/** biome-ignore-all lint/complexity/useArrowFunction: necessary for class prototypes */
|
/** biome-ignore-all lint/complexity/useArrowFunction: necessary for class prototypes */
|
||||||
import { type Equivalence, Function, Predicate } from "effect"
|
import { type Equivalence, Function, Predicate } from "effect"
|
||||||
|
import * as React from "react"
|
||||||
import type * as Component from "./Component.js"
|
import type * as Component from "./Component.js"
|
||||||
|
|
||||||
|
|
||||||
export const TypeId: unique symbol = Symbol.for("@effect-fc/Memoized/Memoized")
|
export const TypeId: unique symbol = Symbol.for("@effect-fc/Memoized/Memoized")
|
||||||
export type TypeId = typeof TypeId
|
export type TypeId = typeof TypeId
|
||||||
|
|
||||||
export interface Memoized<P> extends Memoized.Options<P> {
|
export interface Memoized<P> extends MemoizedOptions<P> {
|
||||||
readonly [TypeId]: TypeId
|
readonly [TypeId]: TypeId
|
||||||
}
|
}
|
||||||
|
|
||||||
export namespace Memoized {
|
export interface MemoizedOptions<P> {
|
||||||
export interface Options<P> {
|
readonly propsEquivalence?: Equivalence.Equivalence<P>
|
||||||
readonly propsAreEqual?: Equivalence.Equivalence<P>
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
const MemoizedProto = Object.freeze({
|
export const MemoizedPrototype = Object.freeze({
|
||||||
[TypeId]: TypeId
|
[TypeId]: TypeId,
|
||||||
|
|
||||||
|
transformFunctionComponent<P extends {}>(
|
||||||
|
this: Memoized<P>,
|
||||||
|
f: React.FC<P>,
|
||||||
|
) {
|
||||||
|
return React.memo(f, this.propsEquivalence)
|
||||||
|
},
|
||||||
} as const)
|
} as const)
|
||||||
|
|
||||||
|
|
||||||
@@ -29,22 +35,22 @@ export const memoized = <T extends Component.Component<any, any, any, any>>(
|
|||||||
): T & Memoized<Component.Component.Props<T>> => Object.setPrototypeOf(
|
): T & Memoized<Component.Component.Props<T>> => Object.setPrototypeOf(
|
||||||
Object.assign(function() {}, self),
|
Object.assign(function() {}, self),
|
||||||
Object.freeze(Object.setPrototypeOf(
|
Object.freeze(Object.setPrototypeOf(
|
||||||
Object.assign({}, MemoizedProto),
|
Object.assign({}, MemoizedPrototype),
|
||||||
Object.getPrototypeOf(self),
|
Object.getPrototypeOf(self),
|
||||||
)),
|
)),
|
||||||
)
|
)
|
||||||
|
|
||||||
export const withOptions: {
|
export const withOptions: {
|
||||||
<T extends Component.Component<any, any, any, any> & Memoized<any>>(
|
<T extends Component.Component<any, any, any, any> & Memoized<any>>(
|
||||||
options: Partial<Memoized.Options<Component.Component.Props<T>>>
|
options: Partial<MemoizedOptions<Component.Component.Props<T>>>
|
||||||
): (self: T) => T
|
): (self: T) => T
|
||||||
<T extends Component.Component<any, any, any, any> & Memoized<any>>(
|
<T extends Component.Component<any, any, any, any> & Memoized<any>>(
|
||||||
self: T,
|
self: T,
|
||||||
options: Partial<Memoized.Options<Component.Component.Props<T>>>,
|
options: Partial<MemoizedOptions<Component.Component.Props<T>>>,
|
||||||
): T
|
): T
|
||||||
} = Function.dual(2, <T extends Component.Component<any, any, any, any> & Memoized<any>>(
|
} = Function.dual(2, <T extends Component.Component<any, any, any, any> & Memoized<any>>(
|
||||||
self: T,
|
self: T,
|
||||||
options: Partial<Memoized.Options<Component.Component.Props<T>>>,
|
options: Partial<MemoizedOptions<Component.Component.Props<T>>>,
|
||||||
): T => Object.setPrototypeOf(
|
): T => Object.setPrototypeOf(
|
||||||
Object.assign(function() {}, self, options),
|
Object.assign(function() {}, self, options),
|
||||||
Object.getPrototypeOf(self),
|
Object.getPrototypeOf(self),
|
||||||
|
|||||||
@@ -9,8 +9,8 @@ import { runtime } from "@/runtime"
|
|||||||
|
|
||||||
// Generator version
|
// Generator version
|
||||||
const RouteComponent = Component.makeUntraced(function* AsyncRendering() {
|
const RouteComponent = Component.makeUntraced(function* AsyncRendering() {
|
||||||
const MemoizedAsyncComponentFC = yield* MemoizedAsyncComponent
|
const MemoizedAsyncComponentFC = yield* MemoizedAsyncComponent.use
|
||||||
const AsyncComponentFC = yield* AsyncComponent
|
const AsyncComponentFC = yield* AsyncComponent.use
|
||||||
const [input, setInput] = React.useState("")
|
const [input, setInput] = React.useState("")
|
||||||
|
|
||||||
return (
|
return (
|
||||||
@@ -51,7 +51,7 @@ const RouteComponent = Component.makeUntraced(function* AsyncRendering() {
|
|||||||
|
|
||||||
|
|
||||||
class AsyncComponent extends Component.makeUntraced("AsyncComponent")(function*() {
|
class AsyncComponent extends Component.makeUntraced("AsyncComponent")(function*() {
|
||||||
const SubComponentFC = yield* SubComponent
|
const SubComponentFC = yield* SubComponent.use
|
||||||
|
|
||||||
yield* Effect.sleep("500 millis") // Async operation
|
yield* Effect.sleep("500 millis") // Async operation
|
||||||
// Cannot use React hooks after the async operation
|
// Cannot use React hooks after the async operation
|
||||||
|
|||||||
@@ -23,7 +23,7 @@ const SubComponent = Component.makeUntraced("SubComponent")(function*() {
|
|||||||
const ContextView = Component.makeUntraced("ContextView")(function*() {
|
const ContextView = Component.makeUntraced("ContextView")(function*() {
|
||||||
const [serviceValue, setServiceValue] = React.useState("test")
|
const [serviceValue, setServiceValue] = React.useState("test")
|
||||||
const SubServiceLayer = React.useMemo(() => SubService.Default(serviceValue), [serviceValue])
|
const SubServiceLayer = React.useMemo(() => SubService.Default(serviceValue), [serviceValue])
|
||||||
const SubComponentFC = yield* Effect.provide(SubComponent, yield* Component.useContext(SubServiceLayer))
|
const SubComponentFC = yield* Effect.provide(SubComponent.use, yield* Component.useContextFromLayer(SubServiceLayer))
|
||||||
|
|
||||||
return (
|
return (
|
||||||
<Container>
|
<Container>
|
||||||
|
|||||||
@@ -17,8 +17,8 @@ const RouteComponent = Component.makeUntraced("RouteComponent")(function*() {
|
|||||||
onChange={e => setValue(e.target.value)}
|
onChange={e => setValue(e.target.value)}
|
||||||
/>
|
/>
|
||||||
|
|
||||||
{yield* Effect.map(SubComponent, FC => <FC />)}
|
{yield* Effect.map(SubComponent.use, FC => <FC />)}
|
||||||
{yield* Effect.map(MemoizedSubComponent, FC => <FC />)}
|
{yield* Effect.map(MemoizedSubComponent.use, FC => <FC />)}
|
||||||
</Flex>
|
</Flex>
|
||||||
)
|
)
|
||||||
}).pipe(
|
}).pipe(
|
||||||
|
|||||||
@@ -70,7 +70,7 @@ class RegisterFormView extends Component.makeUntraced("RegisterFormView")(functi
|
|||||||
])
|
])
|
||||||
|
|
||||||
const runPromise = yield* Component.useRunPromise()
|
const runPromise = yield* Component.useRunPromise()
|
||||||
const TextFieldFormInputFC = yield* TextFieldFormInput
|
const TextFieldFormInputFC = yield* TextFieldFormInput.use
|
||||||
|
|
||||||
yield* Component.useOnMount(() => Effect.gen(function*() {
|
yield* Component.useOnMount(() => Effect.gen(function*() {
|
||||||
yield* Effect.addFinalizer(() => Console.log("RegisterFormView unmounted"))
|
yield* Effect.addFinalizer(() => Console.log("RegisterFormView unmounted"))
|
||||||
@@ -117,8 +117,8 @@ class RegisterFormView extends Component.makeUntraced("RegisterFormView")(functi
|
|||||||
|
|
||||||
const RegisterPage = Component.makeUntraced("RegisterPage")(function*() {
|
const RegisterPage = Component.makeUntraced("RegisterPage")(function*() {
|
||||||
const RegisterFormViewFC = yield* Effect.provide(
|
const RegisterFormViewFC = yield* Effect.provide(
|
||||||
RegisterFormView,
|
RegisterFormView.use,
|
||||||
yield* Component.useContext(RegisterForm.Default),
|
yield* Component.useContextFromLayer(RegisterForm.Default),
|
||||||
)
|
)
|
||||||
|
|
||||||
return <RegisterFormViewFC />
|
return <RegisterFormViewFC />
|
||||||
|
|||||||
@@ -10,8 +10,8 @@ const TodosStateLive = TodosState.Default("todos")
|
|||||||
|
|
||||||
const Index = Component.makeUntraced("Index")(function*() {
|
const Index = Component.makeUntraced("Index")(function*() {
|
||||||
const TodosFC = yield* Effect.provide(
|
const TodosFC = yield* Effect.provide(
|
||||||
Todos,
|
Todos.use,
|
||||||
yield* Component.useContext(TodosStateLive),
|
yield* Component.useContextFromLayer(TodosStateLive),
|
||||||
)
|
)
|
||||||
|
|
||||||
return <TodosFC />
|
return <TodosFC />
|
||||||
|
|||||||
@@ -83,7 +83,7 @@ export class Todo extends Component.makeUntraced("Todo")(function*(props: TodoPr
|
|||||||
|
|
||||||
const runSync = yield* Component.useRunSync()
|
const runSync = yield* Component.useRunSync()
|
||||||
const runPromise = yield* Component.useRunPromise<DateTime.CurrentTimeZone>()
|
const runPromise = yield* Component.useRunPromise<DateTime.CurrentTimeZone>()
|
||||||
const TextFieldFormInputFC = yield* TextFieldFormInput
|
const TextFieldFormInputFC = yield* TextFieldFormInput.use
|
||||||
|
|
||||||
|
|
||||||
return (
|
return (
|
||||||
|
|||||||
@@ -14,7 +14,7 @@ export class Todos extends Component.makeUntraced("Todos")(function*() {
|
|||||||
Effect.addFinalizer(() => Console.log("Todos unmounted")),
|
Effect.addFinalizer(() => Console.log("Todos unmounted")),
|
||||||
))
|
))
|
||||||
|
|
||||||
const TodoFC = yield* Todo
|
const TodoFC = yield* Todo.use
|
||||||
|
|
||||||
return (
|
return (
|
||||||
<Container>
|
<Container>
|
||||||
|
|||||||
Reference in New Issue
Block a user