From 391bc17c0283fb70d043b09c22dc5972ded7b6f1 Mon Sep 17 00:00:00 2001 From: Samuel-Brito19 Date: Sat, 7 Sep 2024 13:29:28 -0300 Subject: [PATCH 1/3] Adding JSDocs for all public symbols --- blocks/page.tsx | 11 +++++++++++ blocks/utils.tsx | 10 ++++++++++ components/JsonViewer.tsx | 6 ++++++ components/section.tsx | 3 +++ deco.ts | 30 +++++++++++++++++++++++++++++- hooks/useDevice.ts | 8 +++++++- hooks/usePartialSection.ts | 7 +++++++ hooks/useScript.ts | 8 ++++++++ runtime/features/invoke.ts | 22 ++++++++++++++++++++++ 9 files changed, 103 insertions(+), 2 deletions(-) diff --git a/blocks/page.tsx b/blocks/page.tsx index 39b18869c..2505fafec 100644 --- a/blocks/page.tsx +++ b/blocks/page.tsx @@ -6,6 +6,17 @@ import { createSectionBlock, type SectionModule } from "./section.ts"; export type Page = InstanceOf; +/** + * Creates a new Block object for a section within a component or page. + * + * @param {any} component - The component or element to be used in the section. + * @param {Function} ComponentFunc - A function that renders the component. + * @returns {Block, ResolverLike, string, any, any>} + * A Block object with properties: + * - `Component`: The rendered component. + * - `props`: Props passed to the component. + * - `metadata`: Metadata about the section, including `resolveChain` and `component`. + */ const page: Block< SectionModule, ResolverLike, diff --git a/blocks/utils.tsx b/blocks/utils.tsx index 50ce993fb..3b5035c86 100644 --- a/blocks/utils.tsx +++ b/blocks/utils.tsx @@ -154,7 +154,17 @@ export const fnContextFromHttpContext = ( return isBot ??= isUABot(ctx.request); }, }; + }; +/** + * Applies props to a function and returns the result. + * + * @template TProps, TResp + * @param {Object} func - A function with a `default` property. + * @param {TProps} $live - Props to be applied to the function. + * @param {HttpContext<{ global: any } & RequestState>} ctx - A context object containing global state and request information. + * @returns {PromiseOrValue} The result of the function call with the applied props. + */ export const applyProps = < TProps = any, TResp = any, diff --git a/components/JsonViewer.tsx b/components/JsonViewer.tsx index 1b2a18a43..557cd328e 100644 --- a/components/JsonViewer.tsx +++ b/components/JsonViewer.tsx @@ -44,6 +44,12 @@ const snippet = (json: string) => { ); }; +/** + * Renders a JSON object in a formatted and interactive way. + * + * @param {Props} p - Props for the JSON viewer component. + * @returns {JSX.Element} The rendered JSON viewer component. + */ export default function JsonViewer(p: Props): JSX.Element { const { Head } = useFramework(); return ( diff --git a/components/section.tsx b/components/section.tsx index 25b63239d..35b59ca11 100644 --- a/components/section.tsx +++ b/components/section.tsx @@ -30,6 +30,9 @@ export interface SectionContext extends HttpContext { FallbackWrapper: ComponentType; } +/** + * Preact context for storing section context. + */ export const SectionContext: PreactContext = createContext( undefined, diff --git a/deco.ts b/deco.ts index 24c2c518c..3bb1c89a1 100644 --- a/deco.ts +++ b/deco.ts @@ -119,21 +119,49 @@ export const Context = { }, }; +/** + * Provides methods for accessing and binding request context. + */ export const RequestContext: RequestContextBinder = { + /** + * Returns the active request context. + * + * @returns {RequestContext | undefined} The active request context. + */ active: (): RequestContext | undefined => Context.active().request, + + /** + * Binds a function to the given request context. + * + * @template R, TArgs + * @param {RequestContext} request - The request context. + * @param {Function} f - The function to bind. + * @returns {Function} The bound function. + */ bind: ( request: RequestContext, f: (...args: TArgs) => R, ): (...args: TArgs) => R => { return Context.bind({ ...Context.active(), request }, f); }, + + /** + * Gets the request's signal. + * + * @returns {AbortSignal | undefined} The request's signal. + */ get signal() { return Context.active().request?.signal; }, + + /** + * Gets the request's framework. + * + * @returns {string} The request's framework. Defaults to "fresh". + */ get framework() { return Context.active().request?.framework ?? "fresh"; }, }; - // deno-lint-ignore no-explicit-any export const context: DecoContext = Context.active(); diff --git a/hooks/useDevice.ts b/hooks/useDevice.ts index 4fb7afea9..071d7f041 100644 --- a/hooks/useDevice.ts +++ b/hooks/useDevice.ts @@ -1,8 +1,14 @@ import { useContext } from "preact/hooks"; import { SectionContext } from "../components/section.tsx"; -import { Device } from "../utils/userAgent.ts"; +import type { Device } from "../utils/userAgent.ts"; +/** + * Hook to access the device information. + * + * @throws {Error} - Throws an error if used on the browser or when context is missing. + * @returns {Device} The device information. + */ export const useDevice = (): Device => { const ctx = useContext(SectionContext); diff --git a/hooks/usePartialSection.ts b/hooks/usePartialSection.ts index f980538ab..f458e0d3d 100644 --- a/hooks/usePartialSection.ts +++ b/hooks/usePartialSection.ts @@ -12,6 +12,13 @@ interface PartialSectionAttrs { "f-partial": string; } +/** + * Hook to create attributes for a partial section component. + * + * @template P - Type of the partial section props + * @param {Options

} props - Optional props for the partial section. + * @returns {PartialSectionAttrs} An object containing attributes for the partial section. + */ export const usePartialSection =

( props: Options

= {}, ): PartialSectionAttrs => ({ diff --git a/hooks/useScript.ts b/hooks/useScript.ts index fbcccab23..83a40ace8 100644 --- a/hooks/useScript.ts +++ b/hooks/useScript.ts @@ -59,6 +59,14 @@ const minify = async (js: string) => { } }; +/** + * Hook to create a minified script tag from a function. + * + * @template T - Type of the function to be used as script + * @param {T} fn - The function to be included as a script. + * @param {...Parameters} params - Parameters to be passed to the function. + * @returns {string} The minified script tag content. + */ export function useScript any>( fn: T, ...params: Parameters diff --git a/runtime/features/invoke.ts b/runtime/features/invoke.ts index 43021d4d3..34a806867 100644 --- a/runtime/features/invoke.ts +++ b/runtime/features/invoke.ts @@ -44,6 +44,12 @@ const isInvokeFunc = ( return (p as InvokeFunction).key !== undefined; }; +/** + * Converts an invoke payload into a resolvable object. + * + * @param {InvokePayload} p - The invoke payload. + * @returns {Resolvable} The resolvable object. + */ export const payloadToResolvable = ( p: InvokePayload, ): Resolvable => { @@ -58,6 +64,13 @@ export const payloadToResolvable = ( return resolvable; }; +/** + * Invokes multiple payloads in a batch. + * + * @param {InvokePayload} payload - The batch payload containing invocations. + * @param {State} state - The application state. + * @returns {Promise} Promise resolving to the result of the batch invocation. + */ export const batchInvoke = ( payload: InvokePayload, state: State, @@ -70,6 +83,15 @@ export const batchInvoke = ( ).catch(wrapInvokeErr(state.correlationId ?? crypto.randomUUID())); }; +/** + * Invokes a function within the application state. + * + * @param {InvokeFunction["key"]} key - The key of the function to invoke. + * @param {InvokeFunction["props"]} props - Props to be passed to the function. + * @param {InvokeFunction["select"]} select - The selection path for the function. + * @param {State} state - The application state. + * @returns {Promise} Promise resolving to the result of the invocation. + */ export const invoke = async ( key: InvokeFunction["key"], props: InvokeFunction["props"], From a41cb4564a2bcd6c60dd0a75c19af26a979ed92a Mon Sep 17 00:00:00 2001 From: Samuel-Brito19 Date: Sat, 7 Sep 2024 15:51:01 -0300 Subject: [PATCH 2/3] adding more jsdocs --- runtime/fetch/mod.ts | 7 +++++++ runtime/handler.tsx | 16 ++++++++++++++++ runtime/routes/entrypoint.tsx | 10 ++++++++++ 3 files changed, 33 insertions(+) diff --git a/runtime/fetch/mod.ts b/runtime/fetch/mod.ts index d055f014a..b7aa33135 100644 --- a/runtime/fetch/mod.ts +++ b/runtime/fetch/mod.ts @@ -13,6 +13,13 @@ interface FechInfo { ): Promise; } +/** + * A modified fetch function that includes logging and caching features. + * + * @type {FechInfo} + * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/fetch} + */ + export const fetch: FechInfo = [ withLogs, ENABLE_LOADER_CACHE ? undefined : withCache, diff --git a/runtime/handler.tsx b/runtime/handler.tsx index e4d3827cc..ab4d3eac9 100644 --- a/runtime/handler.tsx +++ b/runtime/handler.tsx @@ -95,14 +95,30 @@ const routes: Array< }, ]; +/** + * Preact context for storing the application framework. + */ export const FrameworkContext = createContext( undefined, ); +/** + * Hook to access the application framework from context. + * + * @throws {Error} - Throws an error if framework is not set in context. + * @returns {Framework} The application framework. + */ export const useFramework = (): Framework => { return useContext(FrameworkContext)!; }; +/** + * Creates a handler function for a decorated application manifest. + * + * @template TAppManifest extends AppManifest = AppManifest - Type of the application manifest. + * @param {Deco} deco - The decorated application manifest. + * @returns {(req: Request, bindings?: DecoRouteState["Bindings"]) => Promise | Response} - The handler function for the application. + */ export const handlerFor = ( deco: Deco, ): ( diff --git a/runtime/routes/entrypoint.tsx b/runtime/routes/entrypoint.tsx index b62dff616..b2ecee92e 100644 --- a/runtime/routes/entrypoint.tsx +++ b/runtime/routes/entrypoint.tsx @@ -23,6 +23,11 @@ const ctx = createContext(undefined); const routerCtx = createContext(undefined); +/** + * Hook to access the page context. + * + * @returns {PageContext | undefined} The page context, or undefined if not available. + */ export const usePageContext = (): PageContext | undefined => { const pageCtx = useContext(ctx); if (pageCtx === undefined) { @@ -33,6 +38,11 @@ export const usePageContext = (): PageContext | undefined => { return pageCtx; }; +/** + * Hook to access the router context. + * + * @returns {RouterContext | undefined} The router context, or undefined if not available. + */ export const useRouterContext = (): RouterContext | undefined => { const routerCtxImpl = useContext(routerCtx); if (routerCtxImpl === undefined) { From f680f5dd5f8d0f93f406d766a198bb6aafa3e18c Mon Sep 17 00:00:00 2001 From: Samuel-Brito19 Date: Tue, 10 Sep 2024 15:51:32 -0300 Subject: [PATCH 3/3] Change docs in page and applyProps --- blocks/page.tsx | 3 ++- blocks/utils.tsx | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/blocks/page.tsx b/blocks/page.tsx index 2505fafec..375bc1bd3 100644 --- a/blocks/page.tsx +++ b/blocks/page.tsx @@ -7,7 +7,8 @@ import { createSectionBlock, type SectionModule } from "./section.ts"; export type Page = InstanceOf; /** - * Creates a new Block object for a section within a component or page. + * Defines a Page block. + * Pages are JSX-based components and can be rendered by any JSX-compliant library like react or preact. * * @param {any} component - The component or element to be used in the section. * @param {Function} ComponentFunc - A function that renders the component. diff --git a/blocks/utils.tsx b/blocks/utils.tsx index 3b5035c86..7942f8c60 100644 --- a/blocks/utils.tsx +++ b/blocks/utils.tsx @@ -157,7 +157,7 @@ export const fnContextFromHttpContext = ( }; /** - * Applies props to a function and returns the result. + * Applies the given props to the target block function. * * @template TProps, TResp * @param {Object} func - A function with a `default` property.