@4riders/reform 3.0.24

package/src/reform/observers/observerPath.ts

@@ -0,0 +1,327 @@
+import { Path } from "../../yop/ObjectsUtil"
+
+
+/**
+ * State constants for the observer path parser state machine.
+ * @ignore
+ */
+const SLASH = 1
+const OPEN_BRACKET = 2
+const SINGLE_QUOTE = 3
+const DOUBLE_QUOTE = 4
+const CLOSE_QUOTE = 5
+const CLOSE_BRACKET = 6
+
+
+/**
+ * Type representing the parser state.
+ * @ignore
+ */
+type State = typeof SLASH | typeof OPEN_BRACKET | typeof SINGLE_QUOTE | typeof DOUBLE_QUOTE | typeof CLOSE_QUOTE | typeof CLOSE_BRACKET | undefined
+
+
+/**
+ * Represents a segment of an observer path.
+ * @property kind - The type of path segment (e.g., property, index, wildcard).
+ * @property value - The value of the segment, if applicable.
+ * @ignore
+ */
+type PathElement = {
+    kind: 'root' | 'parent' | 'property' | 'key' | 'index' | 'wildcard-index' | 'wildcard' | 'double-wildcard'
+    value?: string | number
+}
+
+
+/**
+ * Regular expression to match valid JavaScript identifiers.
+ * @ignore
+ */
+const identifier = /^[$_\p{ID_Start}][$\p{ID_Continue}]*$/u
+
+/**
+ * Pushes a property, wildcard, or double-wildcard segment to the segments array.
+ * @param segment - The string segment to parse.
+ * @param segments - The array to push the parsed PathElement into.
+ * @returns True if the segment was valid and pushed, false otherwise.
+ * @ignore
+ */
+function pushProperty(segment: string, segments: PathElement[]): boolean {
+    if (identifier.test(segment))
+        segments.push({ kind: "property", value: segment })
+    else if (segment === '*')
+        segments.push({ kind: "wildcard" })
+    else if (segment === '**')
+        segments.push({ kind: "double-wildcard" })
+    else
+        return false
+    return true
+}
+
+/**
+ * Splits an observer path into its constituent segments.
+ * @param path - The observer path string.
+ * @param cache - Optional cache to store and retrieve previously parsed paths.
+ * @returns An array of PathElement objects representing the path segments, or undefined if the path is invalid.
+ * @ignore
+ */
+export function splitObserverPath(path: string, cache?: Map<string, PathElement[]>): PathElement[] | undefined {
+
+    if (path.length === 0)
+        return undefined
+
+    if (cache != null) {
+        const cached = cache.get(path)
+        if (cached != null)
+            return cached.slice()
+    }
+
+    const segments: PathElement[] = []
+
+    let state: State = undefined,
+        escape = false,
+        segment = "",
+        i = 0
+    
+    if (path.charAt(0) === '/' ) {
+        segments.push({ kind: "root" })
+        state = SLASH
+        i++
+    }
+    else {
+        while (path.startsWith("..", i)) {
+            segments.push({ kind: "parent" })
+            i += 2
+            if (i === path.length)
+                return segments
+            const c = path.charAt(i)
+            if (c === '/' ) {
+                i++
+                state = SLASH
+            }
+            else if (c === '[') {
+                i++
+                state = OPEN_BRACKET
+                break
+            }
+            else
+                return undefined
+        }
+    }
+
+    for ( ; i < path.length; i++) {
+        let c = path.charAt(i)
+
+        switch (c) {
+
+            case '\\':
+                if (state !== SINGLE_QUOTE && state !== DOUBLE_QUOTE)
+                    return undefined
+                if (escape)
+                    segment += '\\'
+                escape = !escape
+                continue
+
+            case ' ': case '\t': case '\r': case '\n': case '.':
+                if (state !== SINGLE_QUOTE && state !== DOUBLE_QUOTE)
+                    return undefined
+                segment += c
+                break
+
+            case '/':
+                if (state === SINGLE_QUOTE || state === DOUBLE_QUOTE)
+                    segment += c
+                else if (state === CLOSE_BRACKET) {
+                    if (segment)
+                        return undefined
+                    state = SLASH
+                }
+                else if (state === undefined || state === SLASH) {
+                    if (!pushProperty(segment, segments))
+                        return undefined
+                    segment = ""
+                    state = SLASH
+                }
+                else
+                    return undefined
+                break
+
+            case '[':
+                if (state === SINGLE_QUOTE || state === DOUBLE_QUOTE)
+                    segment += c
+                else if (state === SLASH) {
+                    if (!pushProperty(segment, segments))
+                        return undefined
+                    segment = ""
+                    state = OPEN_BRACKET
+                }
+                else if (state === CLOSE_BRACKET) {
+                    if (segment)
+                        return undefined
+                    state = OPEN_BRACKET
+                }
+                else if (state === undefined) {
+                    if (segment) {
+                        if (!pushProperty(segment, segments))
+                            return undefined
+                        segment = ""
+                    }
+                    state = OPEN_BRACKET
+                }
+                else
+                    return undefined
+                break
+
+            case ']':
+                if (state === SINGLE_QUOTE || state === DOUBLE_QUOTE)
+                    segment += c
+                else if (state === OPEN_BRACKET) {
+                    if (!segment)
+                        return undefined
+                    if (segment === '*')
+                        segments.push({ kind: "wildcard-index" })
+                    else
+                        segments.push({ kind: "index", value: parseInt(segment, 10) })
+                    segment = ""
+                    state = CLOSE_BRACKET
+                }
+                else if (state === CLOSE_QUOTE) {
+                    segments.push({ kind: "key", value: segment })
+                    segment = ""
+                    state = CLOSE_BRACKET
+                }
+                else
+                    return undefined
+                break
+
+            case '\'':
+                if (escape || state === DOUBLE_QUOTE)
+                    segment += c
+                else if (state === SINGLE_QUOTE)
+                    state = CLOSE_QUOTE
+                else if (state === OPEN_BRACKET && !segment)
+                    state = SINGLE_QUOTE
+                else
+                    return undefined
+                break
+
+            case '"':
+                if (escape || state === SINGLE_QUOTE)
+                    segment += c
+                else if (state === DOUBLE_QUOTE)
+                    state = CLOSE_QUOTE
+                else if (state === OPEN_BRACKET && !segment)
+                    state = DOUBLE_QUOTE
+                else
+                    return undefined
+                break
+
+            default:
+                if (state === CLOSE_QUOTE)
+                    return undefined
+                if (state === OPEN_BRACKET) {
+                    if (c === '*') {
+                        if (segment.length > 0)
+                            return undefined
+                    }
+                    else if (c >= '0' && c <= '9') {
+                        if (segment === '*')
+                            return undefined
+                    }
+                    else
+                        return undefined
+                }
+                segment += c
+                break
+        }
+
+        escape = false
+    }
+
+    switch (state) {
+        case undefined:
+            if (segment && !pushProperty(segment, segments))
+                return undefined
+            break
+        case CLOSE_BRACKET:
+            if (segment)
+                return undefined
+            break
+        case SLASH:
+            if (segment && !pushProperty(segment, segments))
+                return undefined
+            break
+        default:
+            return undefined
+    }
+
+    if (cache != null) {
+        if (cache.size >= 500)
+            cache.clear()
+        cache.set(path, segments.slice())
+    }
+
+    return segments
+}
+
+
+/**
+ * Regular expression to match RegExp special characters.
+ * @ignore
+ */
+const reRegExpChar = /[\\^$.*+?()[\]{}|]/g
+/**
+ * Precompiled RegExp to test for RegExp special characters.
+ * @ignore
+ */
+const reHasRegExpChar = RegExp(reRegExpChar.source)
+/**
+ * Escapes RegExp special characters in a string.
+ * @param s - The string to escape.
+ * @returns The escaped string.
+ * @ignore
+ */
+const escapeRegExp = (s: string) => s && reHasRegExpChar.test(s) ? s.replace(reRegExpChar, '\\$&') : s
+
+/**
+ * Converts an observer path (as PathElement array) to a regular expression string for matching actual paths.
+ *
+ * @param observerPath - The parsed observer path as an array of PathElement.
+ * @param currentPath - The current path context for resolving relative paths.
+ * @returns A regular expression string, or undefined if the path is invalid.
+ * @ignore
+ */
+export function observerPathToRegexp(observerPath: PathElement[] | undefined, currentPath: Path): string | undefined {
+    if (observerPath == null || observerPath.length === 0)
+        return undefined
+
+    if (observerPath[0].kind === 'root')
+        observerPath.shift()
+    else {
+        const parentPath = currentPath.slice(0, -1)
+        while (observerPath[0].kind === 'parent') {
+            if (parentPath.pop() == null)
+                return undefined
+            observerPath.shift()
+        }
+        observerPath.unshift(...parentPath.map(segment => ({ kind: typeof segment === "number" ? "index" : "property", value: segment } as PathElement)))
+    }
+
+    const regexPath = observerPath.map((segment, index) => {
+        switch (segment.kind) {
+            case 'wildcard':
+                return (index === 0 ? "" : "\\.") + "[$_\\p{ID_Start}][$\\p{ID_Continue}]*"
+            case 'double-wildcard':
+                return (index === 0 ? "" : "\\.") + ".*"
+            case 'wildcard-index':
+                return "\\[[0-9]+\\]"
+            case "key":
+                return `\\['${ escapeRegExp(segment.value as string) }'\\]`
+            case "index":
+                return Number.isNaN(segment.value) ? "\\[[0-9]+\\]" : `\\[${ (segment.value as number).toFixed(0) }\\]`
+            default: // case "property":
+                return (index === 0 ? "" : "\\.") + escapeRegExp(segment.value as string)
+        }
+    })
+
+    return `^${ regexPath.join('') }$`
+}

package/src/reform/observers/useObservers.ts

@@ -0,0 +1,232 @@
+import { useEffect } from "react"
+import { getClassConstructor, getMetadataFields } from "../../yop/Metadata"
+import { Path, splitPath } from "../../yop/ObjectsUtil"
+import { ClassConstructor } from "../../yop/TypesUtil"
+import { FormManager, ReformSetValueEvent, SetValueOptions } from "../FormManager"
+import { ObserverCallbackContext, ObserverCallbackOptions, ObserverMetadata, ObserversField, observer } from "./observer"
+import { observerPathToRegexp, splitObserverPath } from "./observerPath"
+
+/**
+ * Holds observer metadata and its associated path.
+ * @template T - The type of the observed value.
+ * @ignore
+ */
+type ObserverData<T> = {
+    observer: ObserverMetadata<T>
+    path: Path
+}
+
+/**
+ * Recursively collects all observers from a model and its fields, populating the observers map.
+ * @template T
+ * @param path - The current path in the model.
+ * @param model - The class constructor to inspect.
+ * @param observersMap - The map to populate with observer data.
+ * @ignore
+ */
+function collectObservers<T>(path: Path, model: ClassConstructor<any>, observersMap: Map<string, ObserverData<T>[]>) {
+    const metadata = getMetadataFields(model) as Record<string, ObserversField>
+
+    Object.entries(metadata ?? {}).forEach(([name, fieldMetadata]) => {
+        const isArray = fieldMetadata.kind === "array"
+        
+        path.push(name)
+        if (isArray)
+            path.push(Number.NaN)
+
+        fieldMetadata.observers?.forEach(observer => {
+            const observerPath = splitObserverPath(observer.path)
+            if (observerPath != null) {
+                const pathRegExp = observerPathToRegexp(observerPath, path)
+                if (pathRegExp != null) {
+                    let observersData = observersMap.get(pathRegExp)
+                    if (observersData == null) {
+                        observersData = []
+                        observersMap.set(pathRegExp, observersData)
+                    }
+                    observersData.push({ observer, path: path.concat() })
+                }
+            }
+        })
+
+        const fieldModel = getClassConstructor(fieldMetadata)
+        if (fieldModel != null)
+            collectObservers(path, fieldModel as ClassConstructor<any>, observersMap)
+        
+        if (isArray)
+            path.pop()
+        path.pop()
+    })
+}
+
+
+/**
+ * Tracks whether setValue was called during observer execution.
+ * @ignore
+ */
+type SetValueCalled = { value: boolean }
+
+/**
+ * Creates the context object passed to observer callbacks.
+ * @template T
+ * @param path - The path to the field being observed.
+ * @param value - The current value at the path.
+ * @param event - The event that triggered the observer.
+ * @param setValueCalled - Tracks if setValue was called.
+ * @returns The observer callback context.
+ * @ignore
+ */
+function createCallbackContext<T>(path: Path, value: any, event: ReformSetValueEvent, setValueCalled: SetValueCalled): ObserverCallbackContext<T> {
+    return {
+        path: path,
+        observedValue: event.detail.value,
+        currentValue: value,
+        setValue: (value: any, options?: ObserverCallbackOptions) => {
+            const setValueOptions: SetValueOptions = { touch: true, propagate: false }
+            if (options != null) {
+                if (options.untouch === true)
+                    setValueOptions.touch = false
+                if (options.propagate === true)
+                    setValueOptions.propagate = true
+            }
+            event.detail.form.setValue(path, value, setValueOptions)
+            setValueCalled.value = true
+        },
+        event,
+    }
+}
+
+/**
+ * Recursively calls observer callbacks for matching paths and values.
+ * @param observerData - The observer metadata and path.
+ * @param value - The current value at the path.
+ * @param startPath - The starting path for recursion.
+ * @param path - The remaining path to traverse.
+ * @param event - The event that triggered the observer.
+ * @param setValueCalled - Tracks if setValue was called.
+ * @ignore
+ */
+function callObservers(observerData: ObserverData<any>, value: any, startPath: Path, path: Path, event: ReformSetValueEvent, setValueCalled: SetValueCalled) {
+    if (path.length === 0 || value == null)
+        return
+
+    const pathElement = path[0]
+    if (typeof pathElement === "string") {
+        if (pathElement in value) {
+            value = value[pathElement]
+            if (path.length === 1)
+                observerData.observer.callback(createCallbackContext(startPath.concat(pathElement), value, event, setValueCalled))
+            else if (value != null)
+                callObservers(observerData, value, startPath.concat(pathElement), path.slice(1), event, setValueCalled)
+        }
+    }
+    else if (Array.isArray(value)) {
+        const itemPath = path.slice(1)
+
+        if (Number.isNaN(pathElement)) {
+            value.forEach((item, itemIndex) => {
+                if (item != null) {
+                    const newStartPath = startPath.concat(itemIndex)
+                    if (itemPath.length === 0)
+                        observerData.observer.callback(createCallbackContext(newStartPath, item, event, setValueCalled))
+                    else
+                        callObservers(observerData, item, newStartPath, itemPath, event, setValueCalled)
+                }
+            })
+        }
+        else {
+            const item = value[pathElement]
+            if (item != null) {
+                const newStartPath = startPath.concat(pathElement)
+                if (itemPath.length === 0)
+                    observerData.observer.callback(createCallbackContext(newStartPath, item, event, setValueCalled))
+                else
+                    callObservers(observerData, item, newStartPath, itemPath, event, setValueCalled)
+            }
+        }
+    }
+}
+
+/**
+ * Creates an event listener that triggers observers for a given model.
+ * @param model - The class constructor to observe.
+ * @returns An event listener for reform events.
+ * @ignore
+ */
+function createReformEventListener(model: ClassConstructor<any>) {
+    const observersMap = new Map<string, ObserverData<any>[]>()
+    collectObservers([], model, observersMap)
+    const observers = Array.from(observersMap.entries()).map(([path, observerData]) => [new RegExp(path, "u"), observerData]) as [RegExp, ObserverData<any>[]][]
+
+    return ((event: ReformSetValueEvent) => {
+        const values = event.detail.form.values
+        if (values == null)
+            return
+
+        const eventPath = splitPath(event.detail.path) ?? []
+        const setValueCalled = { value: false }
+        
+        observers.forEach(([pathRegExp, observersData]) => {
+            if (pathRegExp.test(event.detail.path)) {
+                observersData.forEach(observerData => {
+                    let value: any = values
+                    const startPath: Path = []
+                    if (observerData.observer.path[0] !== '/') {
+                        for (let i = 0; i < observerData.path.length && i < eventPath.length; i++) {
+                            const pathSegment = observerData.path[i]
+                            const eventSegment = eventPath[i]
+                            if (pathSegment !== eventSegment && !(Number.isNaN(pathSegment) && (typeof eventSegment === "number")))
+                                break
+                            startPath.push(eventSegment)
+                            value = value[eventSegment]
+                            if (value == null)
+                                break
+                        }
+                    }
+                    const path = (startPath.length > 0 ? observerData.path.slice(startPath.length) : observerData.path)
+                    callObservers(observerData, value, startPath, path, event, setValueCalled)
+                })
+            }
+        })
+        
+        if (setValueCalled.value) {
+            event.detail.form.validate()
+            event.detail.form.render()
+        }
+    }) as EventListener
+}
+
+/**
+ * React hook to register reform event listeners for {@link observer}s on a model. This hook scans the provided model class for any observer metadata
+ * and registers a single event listener on the form manager instance that will trigger the appropriate observer callbacks when relevant fields
+ * are updated.
+ * 
+ * There is no need to use this hook if you are using the {@link useForm} hook with a model class, as observers will be automatically registered on
+ * the form manager instance.
+ *
+ * Example usage:
+ * ```tsx
+ * const form = useForm({
+ *     initialValues: new MyFormModel(),
+ *     validationSchema: instance({ of: MyFormModel }),
+ *     onSubmit: (form) => { ... }
+ * })
+ * useObservers(MyFormModel, form)
+ * ```
+ *
+ * @template T
+ * @param model - The class constructor to scan for observers.
+ * @param form - The form manager instance holding the values to observe.
+ * @category Observers
+ */
+export function useObservers<T extends object>(model: ClassConstructor<T> | null | undefined, form: FormManager<unknown>) {
+    useEffect(() => {
+        if (model != null) {
+            const reformEventListener = createReformEventListener(model)
+            form.addReformEventListener(reformEventListener)
+            return () => {
+                form.removeReformEventListener(reformEventListener)
+            }
+        }
+    }, [model])
+}