@ispb/react-lazy 0.0.1

package/.yarnrc.yml

@@ -0,0 +1,8 @@
+approvedGitRepositories:
+  - "**"
+
+enableScripts: true
+
+nodeLinker: node-modules
+
+npmMinimalAgeGate: 0

package/package.json

@@ -0,0 +1,30 @@
+{
+    "name": "@ispb/react-lazy",
+    "version": "0.0.1",
+    "license": "MIT",
+    "type": "module",
+    "sideEffects": false,
+    "scripts": {
+        "build": "tsc",
+        "watch": "tsc --watch"
+    },
+    "exports": {
+        "default": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+    },
+    "dependencies": {
+        "p-defer": "^4.0.1",
+        "rxjs": "^7.8.2",
+        "state-hooks": "file:../state-hooks",
+        "value-or-factory": "^0.0.1"
+    },
+    "peerDependencies": {
+        "react": "^18.3.1"
+    },
+    "devDependencies": {
+        "@types/react": "^19.2.7",
+        "react": "^18.3.1",
+        "typescript": "^5.9.3"
+    },
+    "packageManager": "yarn@4.18.0"
+}

package/src/async.tsx

@@ -0,0 +1,124 @@
+
+import { ReactNode, useCallback, useEffect, useState } from "react"
+import { ValueOrFactory, callOrGet } from "value-or-factory"
+import { Lazy } from "./components.js"
+import { LazyHOCOptions, lazified } from "./hoc.js"
+import { useIsFirstMount } from "./internal.js"
+import { LazyState } from "./state.js"
+import { LazyEvent, LazyOverrides } from "./types.js"
+
+/**
+ * Options for the async hook.
+ * @typeParam D The data type.
+ */
+export interface AsyncLazyOptions<D> {
+
+    /**
+     * A promise or a function that returns a promise. This MUST be memoized - the function will re-run every time a new value is received.
+     */
+    readonly promise: ValueOrFactory<PromiseLike<D>>
+
+    /**
+     * Don't execute immediately.
+     */
+    readonly defer?: AsyncLazyDefer<D> | undefined
+
+}
+
+export interface AsyncLazyDefer<D> {
+
+    /**
+     * The initial value to provide.
+     */
+    readonly initial: D
+
+}
+
+export type AsyncLazyEvent<D> = LazyEvent<D> & { readonly retry: Retry }
+
+export function useAsyncLazy<D>(input: AsyncLazyOptions<D> | (() => PromiseLike<D>)): AsyncLazyEvent<D> {
+    const options = typeof input === "function" ? { promise: input } : input
+    const [event, setEvent] = useState<LazyEvent<D>>(options.defer === undefined ? { status: "loading" } : { status: "fulfilled", value: options.defer.initial })
+    const run = useCallback(() => {
+        callOrGet(options.promise).then(value => {
+            setEvent({
+                status: "fulfilled",
+                value,
+            })
+        }, reason => {
+            setEvent({
+                status: "rejected",
+                reason,
+            })
+        })
+    }, [
+        options.promise
+    ])
+    const retry = useCallback((suppressReload = false) => {
+        if (!suppressReload) {
+            setEvent({
+                status: "loading"
+            })
+        }
+        run()
+    }, [
+        run
+    ])
+    const isFirstMount = useIsFirstMount()
+    useEffect(() => {
+        if (isFirstMount) {
+            if (options.defer !== undefined) {
+                return
+            }
+        }
+        else {
+            setEvent({
+                status: "loading"
+            })
+        }
+        run()
+    }, [
+        run,
+    ])
+    return {
+        ...event,
+        retry
+    }
+}
+
+export type AsyncLazyState<D> = LazyState<D> & { readonly retry: Retry }
+
+export interface AsyncifiedOptions<D, P> extends AsyncLazyOptions<D>, LazyHOCOptions<AsyncLazyState<D>, P> {
+}
+
+export function asyncified<I extends {}, D extends {}, P extends {}>(factory: (props: I) => AsyncifiedOptions<D, P>) {
+    return lazified((props: I) => {
+        const options = factory(props)
+        const event = useAsyncLazy(options)
+        return {
+            event,
+            passthrough: state => callOrGet(options.passthrough, { ...state, retry: event.retry }),
+            overrides: options.overrides,
+        }
+    })
+}
+
+export type Retry = (suppressReload?: boolean | undefined) => void
+
+export interface AsyncifiedProps<D> extends AsyncLazyOptions<D> {
+
+    readonly children: ValueOrFactory<ReactNode, [D, AsyncLazyState<D>]>
+
+    /**
+     * The lazy overrides.
+     */
+    readonly overrides?: LazyOverrides | undefined
+
+}
+
+export const Asyncified = <D,>(props: AsyncifiedProps<D>) => {
+    const event = useAsyncLazy(props)
+    return <Lazy event={event}
+        overrides={props.overrides}
+        children={(value, state) => callOrGet(props.children, value, { ...state, retry: event.retry })} />
+}

package/src/components.tsx

@@ -0,0 +1,46 @@
+
+import { PropsWithChildren, ReactNode, useContext } from "react"
+import { LazyContext } from "./hooks.js"
+import { LazyState, useLazyState } from "./state.js"
+import { LazyEvent, LazyOverrides } from "./types.js"
+
+export interface LazyProps<D> {
+
+    readonly event: LazyEvent<D>
+    readonly overrides?: LazyOverrides | undefined
+    readonly children: ReactNode | ((value: D, state: LazyState<D>) => ReactNode)
+
+}
+
+export function Lazy<D>(props: LazyProps<D>): ReactNode {
+    const context = useContext(LazyContext)
+    const options = { ...context, ...props.overrides }
+    const state = useLazyState(props.event)
+    if (state.isLoading && !state.isSettled) {
+        if (options.onLoading === undefined) {
+            return null
+        }
+        return options.onLoading({
+            message: options.loadingMessage ?? options.defaultMessage
+        })
+    }
+    const onReloading = options.onReloading ?? ((props: PropsWithChildren) => props.children)
+    return onReloading({
+        reloading: state.isLoading,
+        message: options.reloadingMessage ?? options.defaultMessage,
+        children: (() => {
+            if (state.isRejected) {
+                if (options.onError === undefined) {
+                    throw state.reason
+                }
+                return options.onError({
+                    reason: state.reason,
+                    message: options.errorMessage ?? options.defaultMessage,
+                })
+            }
+            else {
+                return typeof props.children === "function" ? props.children(state.value, state) : props.children
+            }
+        })()
+    })
+}

package/src/hoc.tsx

@@ -0,0 +1,37 @@
+
+import { ComponentType, createElement } from "react"
+import { callOrGet, ValueOrFactory } from "value-or-factory"
+import { Lazy } from "./components.js"
+import { LazyState } from "./state.js"
+import { LazyEvent, LazyOverrides } from "./types.js"
+
+export interface LazyBuilder<D, P> extends LazyHOCOptions<LazyState<D>, P> {
+
+    readonly event: LazyEvent<D>
+
+}
+
+export function lazified<I extends {}, D extends {}, P extends {}>(build: (props: I) => LazyBuilder<D, P>) {
+    return (component: ComponentType<D & P>) => {
+        return (props: I) => {
+            const built = build(props)
+            return <Lazy event={built.event}
+                overrides={built.overrides}
+                children={(value, state) => createElement(component, { ...callOrGet(built.passthrough, state), ...value })} />
+        }
+    }
+}
+
+export interface LazyHOCOptions<S, P> {
+
+    /**
+     * Properties to pass through to the component.
+     */
+    readonly passthrough: ValueOrFactory<P, [S]>
+
+    /**
+     * Overrides for lazy settings.
+     */
+    readonly overrides?: LazyOverrides | undefined
+
+}

package/src/hooks.ts

@@ -0,0 +1,155 @@
+import pDefer from "p-defer"
+import { createContext, useEffect, useMemo, useState } from "react"
+import { Observable, Subject } from "rxjs"
+import { useIsFirstMount } from "state-hooks"
+import { ExtractLazy, LazyEvent, LazyFulfilled, LazyLoading, LazyOverrides, LazyRejected } from "./types.js"
+
+export const LazyContext = createContext<LazyOverrides>({})
+
+export function isLoading<T>(event: LazyEvent<T>): event is LazyLoading {
+    if (event.status === "loading") {
+        return true
+    }
+    else {
+        return false
+    }
+}
+export function isFulfilled<T>(event: LazyEvent<T>): event is LazyFulfilled<T> {
+    if (event.status === "fulfilled") {
+        return true
+    }
+    else {
+        return false
+    }
+}
+export function isRejected<T>(event: LazyEvent<T>): event is LazyRejected {
+    if (event.status === "rejected") {
+        return true
+    }
+    else {
+        return false
+    }
+}
+
+export function useLazyFlatten<O>(event: LazyEvent<LazyEvent<O>>,) {
+    return useLazyChain(event, event => event)
+}
+export function useLazyChain<I, O>(event: LazyEvent<I>, map: (value: I) => LazyEvent<O>) {
+    return useMemo(() => {
+        if (event.status === "fulfilled") {
+            return map(event.value)
+        }
+        else {
+            return event
+        }
+    }, [
+        event
+    ])
+}
+export function useLazyMap<I, O>(event: LazyEvent<I>, map: (value: I) => O) {
+    return useMemo(() => {
+        if (event.status === "fulfilled") {
+            return {
+                status: "fulfilled" as const,
+                value: map(event.value)
+            }
+        }
+        else {
+            return event
+        }
+    }, [
+        event
+    ])
+}
+
+export function useObservableAsPromise<T>(observable: Observable<T>) {
+    const [promise, setPromise] = useState(() => pDefer<T>())
+    const isFirstMount = useIsFirstMount()
+    useEffect(() => {
+        if (!isFirstMount) {
+            setPromise(pDefer<T>())
+        }
+    }, [
+        observable
+    ])
+    useEffect(() => {
+        const sub = observable.subscribe({
+            next: value => {
+                promise.resolve(value)
+            },
+            error: reason => {
+                promise.reject(reason)
+            }
+        })
+        return () => {
+            sub.unsubscribe()
+        }
+    }, [
+        promise
+    ])
+    return promise.promise
+}
+
+export function useLazyAsPromise<T>(event: LazyEvent<T>) {
+    const [promise, setPromise] = useState(() => pDefer<T>())
+    useEffect(() => {
+        if (event.status === "fulfilled") {
+            promise.resolve(event.value)
+        }
+        else if (event.status === "rejected") {
+            promise.reject(event.reason)
+        }
+        else {
+            setPromise(pDefer<T>())
+        }
+    }, [
+        event
+    ])
+    return promise.promise
+}
+
+export function useLazyAsObservable<T>(event: LazyEvent<T>) {
+    const subject = useMemo(() => new Subject<T>(), [])
+    useEffect(() => {
+        if (event.status === "fulfilled") {
+            subject.next(event.value)
+        }
+        else if (event.status === "rejected") {
+            subject.error(event.reason)
+        }
+    }, [
+        event
+    ])
+    return subject
+}
+
+export function useLazyCombine<T extends Record<string, LazyEvent<unknown>>>(lazies: T): LazyEvent<{ [K in keyof T]: ExtractLazy<T[K]> }> {
+    const entries = Object.entries(lazies)
+    if (entries.map(entry => entry[1]).some(isLoading)) {
+        return {
+            status: "loading" as const,
+        }
+    }
+    else {
+        const failed = entries.map(entry => entry[1]).filter(isRejected).at(0)
+        if (failed !== undefined) {
+            return {
+                status: "rejected" as const,
+                reason: failed
+            }
+        }
+        else {
+            return {
+                status: "fulfilled",
+                value: Object.fromEntries(
+                    entries.map(([key, value]) => {
+                        return [
+                            key,
+                            value.status === "fulfilled" ? value.value : undefined,
+                        ] as const
+                    })
+                ) as { [K in keyof T]: ExtractLazy<T[K]> }
+            }
+        }
+    }
+}

package/src/index.tsx

@@ -0,0 +1,9 @@
+
+export * from "./async.js"
+export * from "./components.js"
+export * from "./hoc.js"
+export * from "./hooks.js"
+export * from "./observable.js"
+export * from "./state.js"
+export * from "./types.js"
+

package/src/internal.ts

@@ -0,0 +1,21 @@
+import { useRef } from "react"
+
+export function useIsFirstMount() {
+    const isFirst = useRef(true)
+    if (isFirst.current) {
+        isFirst.current = false
+        return true
+    }
+    return isFirst.current
+}
+
+export function usePrevious<T>(value: { readonly current: T } | undefined) {
+    const previous = useRef(value?.current)
+    const first = useIsFirstMount()
+    if (!first) {
+        if (value !== undefined) {
+            previous.current = value.current
+        }
+    }
+    return previous.current
+}

package/src/observable.tsx

@@ -0,0 +1,83 @@
+
+import { ReactNode, useEffect, useState } from "react"
+import { Observable, ObservedValueOf } from "rxjs"
+import { Lazy } from "./components.js"
+import { LazyHOCOptions, lazified } from "./hoc.js"
+import { useLazyFlatten } from "./hooks.js"
+import { useIsFirstMount } from "./internal.js"
+import { LazyState } from "./state.js"
+import { LazyEvent, LazyOverrides } from "./types.js"
+
+export type ObservableLazyInput = Observable<any>// | Record<string, ObservableInput<any>>
+export type ObservableLazyOutput<X extends ObservableLazyInput> = X extends Observable<any> ? ObservedValueOf<X> : { [K in keyof X]: ObservedValueOf<X[K]> }
+
+export interface ObservableLazyOptions<D> {
+
+    readonly of: Observable<D>
+
+}
+
+export function useObservableLazyWrapped<D>(options: ObservableLazyOptions<LazyEvent<D>>) {
+    return useLazyFlatten(useObservableLazy(options))
+}
+
+export function useObservableLazy<D>(options: ObservableLazyOptions<D>) {
+    const [event, setEvent] = useState<LazyEvent<D>>({ status: "loading" as const })
+    const isFirstMount = useIsFirstMount()
+    useEffect(() => {
+        if (!isFirstMount) {
+            setEvent({
+                status: "loading"
+            })
+        }
+        const sub = options.of.subscribe({
+            next: value => {
+                setEvent({
+                    status: "fulfilled",
+                    value
+                })
+            },
+            error: reason => {
+                setEvent({
+                    status: "rejected",
+                    reason
+                })
+            }
+        })
+        return () => {
+            sub.unsubscribe()
+        }
+    }, [
+        options.of
+    ])
+    return event
+}
+
+export interface ObservingOptions<D, P> extends ObservableLazyOptions<D>, LazyHOCOptions<LazyState<D>, P> {
+}
+
+export function observing<I extends {}, D extends {}, P extends {}>(factory: (props: I) => ObservingOptions<D, P>) {
+    return lazified((props: I) => {
+        const options = factory(props)
+        const event = useObservableLazy(options)
+        return {
+            event,
+            passthrough: options.passthrough,
+            overrides: options.overrides,
+        }
+    })
+}
+
+export interface ObservingProps<D> extends ObservableLazyOptions<D> {
+
+    readonly children: (value: D, state: LazyState<D>) => ReactNode
+    readonly overrides?: LazyOverrides | undefined
+
+}
+
+export const Observing = <D,>(props: ObservingProps<D>) => {
+    const event = useObservableLazy(props)
+    return <Lazy event={event}
+        overrides={props.overrides}
+        children={props.children} />
+}

package/src/state.ts

@@ -0,0 +1,99 @@
+import { usePrevious } from "./internal.js"
+import { LazyEvent, LazySettled } from "./types.js"
+
+export type LazyState<D> = {
+    readonly isLoading: true
+    readonly isReloading: false
+    readonly isSettled: false
+    readonly isFulfilled: false
+    readonly isRejected: false
+} | {
+    readonly isLoading: true
+    readonly isReloading: true
+    readonly isSettled: true
+    readonly isFulfilled: true
+    readonly isRejected: false
+    readonly value: D
+} | {
+    readonly isLoading: true
+    readonly isReloading: true
+    readonly isSettled: true
+    readonly isFulfilled: false
+    readonly isRejected: true
+    readonly reason: unknown
+    readonly retry?: (() => void) | undefined
+} | {
+    readonly isLoading: false
+    readonly isReloading: false
+    readonly isSettled: true
+    readonly isFulfilled: true
+    readonly isRejected: false
+    readonly value: D
+} | {
+    readonly isLoading: false
+    readonly isReloading: false
+    readonly isSettled: true
+    readonly isFulfilled: false
+    readonly isRejected: true
+    readonly reason: unknown
+    readonly retry?: (() => void) | undefined
+}
+
+export function useLazyState<D>(current: LazyEvent<D>): LazyState<D> {
+    const settled = usePrevious<LazySettled<D>>(current.status === "fulfilled" || current.status === "rejected" ? { current } : undefined)
+    if (current.status === "loading") {
+        if (settled === undefined) {
+            return {
+                isLoading: true,
+                isReloading: false,
+                isSettled: false,
+                isFulfilled: false,
+                isRejected: false,
+            }
+        }
+        else {
+            if (settled.status === "fulfilled") {
+                return {
+                    isLoading: true,
+                    isReloading: true,
+                    isSettled: true,
+                    isFulfilled: true,
+                    isRejected: false,
+                    value: settled.value,
+                }
+            }
+            else {
+                return {
+                    isLoading: true,
+                    isReloading: true,
+                    isSettled: true,
+                    isFulfilled: false,
+                    isRejected: true,
+                    reason: settled.reason,
+                    retry: settled.retry,
+                }
+            }
+        }
+    }
+    if (current.status === "fulfilled") {
+        return {
+            isLoading: false,
+            isReloading: false,
+            isSettled: true,
+            isFulfilled: true,
+            isRejected: false,
+            value: current.value,
+        }
+    }
+    else {
+        return {
+            isLoading: false,
+            isReloading: false,
+            isSettled: true,
+            isFulfilled: false,
+            isRejected: true,
+            reason: current.reason,
+            retry: current.retry,
+        }
+    }
+}

package/src/types.tsx

@@ -0,0 +1,75 @@
+import { ReactNode } from "react"
+
+export type LazyLoading = { readonly status: "loading" }
+export type LazyFulfilled<D> = { readonly status: "fulfilled", readonly value: D }
+export type LazyRejected = { readonly status: "rejected", readonly reason: unknown, readonly retry?: (() => void) | undefined }
+export type LazySettled<D> = LazyFulfilled<D> | LazyRejected
+export type LazyEvent<D> = LazySettled<D> | LazyLoading
+
+export type OnLoading = (props: LoadingProps) => ReactNode
+export type OnReloading = (props: ReloadingProps) => ReactNode
+export type OnError = (props: ErrorProps) => ReactNode
+
+type LazyMeta = string
+
+export interface LoadingProps {
+
+    /**
+     * The message to display.
+     */
+    readonly message?: LazyMeta | undefined
+
+}
+
+export interface ReloadingProps {
+
+    /**
+     * Whether or not the data is currently reloading.
+     */
+    readonly reloading: boolean
+
+    /**
+     * The message to display.
+     */
+    readonly message?: LazyMeta | undefined
+
+    /**
+     * The children.
+     */
+    readonly children: ReactNode
+
+}
+
+export interface ErrorProps {
+
+    /**
+     * The error.
+     */
+    readonly reason: unknown
+
+    /**
+     * The message to display.
+     */
+    readonly message?: LazyMeta | undefined
+
+}
+
+export interface LazyOptions {
+
+    readonly onLoading?: OnLoading | undefined
+    readonly onReloading?: OnReloading | undefined
+    readonly onError?: OnError | undefined
+
+    readonly defaultMessage?: LazyMeta | undefined
+    readonly loadingMessage?: LazyMeta | undefined
+    readonly reloadingMessage?: LazyMeta | undefined
+    readonly errorMessage?: LazyMeta | undefined
+
+}
+
+/**
+ * Overrides for lazy options.
+ */
+export type LazyOverrides = Partial<LazyOptions>
+
+export type ExtractLazy<T> = T extends LazyFulfilled<infer D> ? D : never

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+    "compilerOptions": {
+        "jsx": "react-jsx",
+        "strict": true,
+        "alwaysStrict": true,
+        "allowUnreachableCode": false,
+        "allowUnusedLabels": false,
+        "noImplicitAny": true,
+        "noImplicitThis": true,
+        "noImplicitOverride": true,
+        "noUnusedLocals": true,
+        "noUnusedParameters": true,
+        "noPropertyAccessFromIndexSignature": true,
+        "noUncheckedIndexedAccess": true,
+        "noFallthroughCasesInSwitch": true,
+        "useUnknownInCatchVariables": true,
+        "exactOptionalPropertyTypes": true,
+        "moduleResolution": "nodenext",
+        "module": "nodenext",
+        "target": "esnext",
+        "declaration": true,
+        "sourceMap": true,
+        "skipLibCheck": true,
+        "rootDir": "src",
+        "outDir": "dist"
+    }
+}