add comments to everything potentially consumer facing (#3127)

* add comments to everything potentially consumer facing * rework smtp --------- Co-authored-by: Aiden McClelland <3732071+dr-bonez@users.noreply.github.com>
2026-04-04 06:19:44 +00:00 · 2026-02-24 14:29:09 -07:00
parent 3974c09369
commit d4e019c87b
51 changed files with 1796 additions and 116 deletions
--- a/sdk/base/lib/actions/input/builder/inputSpec.ts
+++ b/sdk/base/lib/actions/input/builder/inputSpec.ts
@@ -6,19 +6,28 @@ import { z } from 'zod'
 import { DeepPartial } from '../../../types'
 import { InputSpecTools, createInputSpecTools } from './inputSpecTools'

+/** Options passed to a lazy builder function when resolving dynamic form field values. */
 export type LazyBuildOptions<Type> = {
+  /** The effects interface for runtime operations (e.g. reading files, querying state). */
  effects: Effects
+  /** Previously saved form data to pre-fill the form with, or `null` for fresh creation. */
  prefill: DeepPartial<Type> | null
 }
+/**
+ * A function that lazily produces a value, potentially using effects and prefill data.
+ * Used by `dynamic*` variants of {@link Value} to compute form field options at runtime.
+ */
 export type LazyBuild<ExpectedOut, Type> = (
  options: LazyBuildOptions<Type>,
 ) => Promise<ExpectedOut> | ExpectedOut

+/** Extracts the runtime type from an {@link InputSpec}. */
 // prettier-ignore
-export type ExtractInputSpecType<A extends InputSpec<Record<string, any>, any>> = 
+export type ExtractInputSpecType<A extends InputSpec<Record<string, any>, any>> =
  A extends InputSpec<infer B, any> ? B :
  never

+/** Extracts the static validation type from an {@link InputSpec}. */
 export type ExtractInputSpecStaticValidatedAs<
  A extends InputSpec<any, Record<string, any>>,
 > = A extends InputSpec<any, infer B> ? B : never
@@ -27,10 +36,12 @@ export type ExtractInputSpecStaticValidatedAs<
 //   A extends Record<string, any> | InputSpec<Record<string, any>>,
 // > = A extends InputSpec<infer B> ? DeepPartial<B> : DeepPartial<A>

+/** Maps an object type to a record of {@link Value} entries for use with `InputSpec.of`. */
 export type InputSpecOf<A extends Record<string, any>> = {
  [K in keyof A]: Value<A[K]>
 }

+/** A value that is either directly provided or lazily computed via a {@link LazyBuild} function. */
 export type MaybeLazyValues<A, T> = LazyBuild<A, T> | A
 /**
 * InputSpecs are the specs that are used by the os input specification form for this service.
@@ -100,6 +111,11 @@ export class InputSpec<
  ) {}
  public _TYPE: Type = null as any as Type
  public _PARTIAL: DeepPartial<Type> = null as any as DeepPartial<Type>
+  /**
+   * Builds the runtime form specification and combined Zod validator from this InputSpec's fields.
+   *
+   * @returns An object containing the resolved `spec` (field specs keyed by name) and a combined `validator`
+   */
  async build<OuterType>(options: LazyBuildOptions<OuterType>): Promise<{
    spec: {
      [K in keyof Type]: ValueSpec
@@ -123,6 +139,12 @@ export class InputSpec<
    }
  }

+  /**
+   * Adds a single named field to this spec, returning a new `InputSpec` with the extended type.
+   *
+   * @param key - The field key name
+   * @param build - A {@link Value} instance, or a function receiving typed tools that returns one
+   */
  addKey<Key extends string, V extends Value<any, any, any>>(
    key: Key,
    build: V | ((tools: InputSpecTools<Type>) => V),
@@ -146,6 +168,11 @@ export class InputSpec<
    return new InputSpec(newSpec, newValidator as any)
  }

+  /**
+   * Adds multiple fields to this spec at once, returning a new `InputSpec` with extended types.
+   *
+   * @param build - A record of {@link Value} entries, or a function receiving typed tools that returns one
+   */
  add<AddSpec extends Record<string, Value<any, any, any>>>(
    build: AddSpec | ((tools: InputSpecTools<Type>) => AddSpec),
  ): InputSpec<
@@ -174,6 +201,17 @@ export class InputSpec<
    return new InputSpec(newSpec, newValidator as any)
  }

+  /**
+   * Creates an `InputSpec` from a plain record of {@link Value} entries.
+   *
+   * @example
+   * ```ts
+   * const spec = InputSpec.of({
+   *   username: Value.text({ name: 'Username', required: true, default: null }),
+   *   verbose: Value.toggle({ name: 'Verbose Logging', default: false }),
+   * })
+   * ```
+   */
  static of<Spec extends Record<string, Value<any, any>>>(spec: Spec) {
    const validator = z.object(
      Object.fromEntries(
--- a/sdk/base/lib/actions/input/builder/list.ts
+++ b/sdk/base/lib/actions/input/builder/list.ts
@@ -9,6 +9,14 @@ import {
 } from '../inputSpecTypes'
 import { z } from 'zod'

+/**
+ * Builder class for defining list-type form fields.
+ *
+ * A list presents an interface to add, remove, and reorder items. Items can be
+ * either text strings ({@link List.text}) or structured objects ({@link List.obj}).
+ *
+ * Used with {@link Value.list} to include a list field in an {@link InputSpec}.
+ */
 export class List<
  Type extends StaticValidatedAs,
  StaticValidatedAs = Type,
@@ -26,6 +34,12 @@ export class List<
  ) {}
  readonly _TYPE: Type = null as any

+  /**
+   * Creates a list of text input items.
+   *
+   * @param a - List-level options (name, description, min/max length, defaults)
+   * @param aSpec - Item-level options (patterns, input mode, masking, generation)
+   */
  static text(
    a: {
      name: string
@@ -97,6 +111,7 @@ export class List<
    }, validator)
  }

+  /** Like {@link List.text} but options are resolved lazily at runtime via a builder function. */
  static dynamicText<OuterType = unknown>(
    getA: LazyBuild<
      {
@@ -150,6 +165,12 @@ export class List<
    }, validator)
  }

+  /**
+   * Creates a list of structured object items, each defined by a nested {@link InputSpec}.
+   *
+   * @param a - List-level options (name, description, min/max length)
+   * @param aSpec - Item-level options (the nested spec, display expression, uniqueness constraint)
+   */
  static obj<
    Type extends StaticValidatedAs,
    StaticValidatedAs extends Record<string, any>,
--- a/sdk/base/lib/actions/input/builder/value.ts
+++ b/sdk/base/lib/actions/input/builder/value.ts
@@ -15,12 +15,15 @@ import { _, once } from '../../../util'
 import { z } from 'zod'
 import { DeepPartial } from '../../../types'

+/** Zod schema for a file upload result — validates `{ path, commitment: { hash, size } }`. */
 export const fileInfoParser = z.object({
  path: z.string(),
  commitment: z.object({ hash: z.string(), size: z.number() }),
 })
+/** The parsed result of a file upload, containing the file path and its content commitment (hash + size). */
 export type FileInfo = z.infer<typeof fileInfoParser>

+/** Conditional type: returns `T` if `Required` is `true`, otherwise `T | null`. */
 export type AsRequired<T, Required extends boolean> = Required extends true
  ? T
  : T | null
@@ -37,6 +40,19 @@ function asRequiredParser<Type, Input extends { required: boolean }>(
  return parser.nullable() as any
 }

+/**
+ * Core builder class for defining a single form field in a service configuration spec.
+ *
+ * Each static factory method (e.g. `Value.text()`, `Value.toggle()`, `Value.select()`) creates
+ * a typed `Value` instance representing a specific field type. Dynamic variants (e.g. `Value.dynamicText()`)
+ * allow the field options to be computed lazily at runtime.
+ *
+ * Use with {@link InputSpec} to compose complete form specifications.
+ *
+ * @typeParam Type - The runtime type this field produces when filled in
+ * @typeParam StaticValidatedAs - The compile-time validated type (usually same as Type)
+ * @typeParam OuterType - The parent form's type context (used by dynamic variants)
+ */
 export class Value<
  Type extends StaticValidatedAs,
  StaticValidatedAs = Type,
@@ -99,6 +115,7 @@ export class Value<
      validator,
    )
  }
+  /** Like {@link Value.toggle} but options are resolved lazily at runtime via a builder function. */
  static dynamicToggle<OuterType = unknown>(
    a: LazyBuild<
      {
@@ -225,6 +242,7 @@ export class Value<
      validator,
    )
  }
+  /** Like {@link Value.text} but options are resolved lazily at runtime via a builder function. */
  static dynamicText<Required extends boolean, OuterType = unknown>(
    getA: LazyBuild<
      {
@@ -345,6 +363,7 @@ export class Value<
      return { spec: built, validator }
    }, validator)
  }
+  /** Like {@link Value.textarea} but options are resolved lazily at runtime via a builder function. */
  static dynamicTextarea<Required extends boolean, OuterType = unknown>(
    getA: LazyBuild<
      {
@@ -467,6 +486,7 @@ export class Value<
      validator,
    )
  }
+  /** Like {@link Value.number} but options are resolved lazily at runtime via a builder function. */
  static dynamicNumber<Required extends boolean, OuterType = unknown>(
    getA: LazyBuild<
      {
@@ -562,6 +582,7 @@ export class Value<
    )
  }

+  /** Like {@link Value.color} but options are resolved lazily at runtime via a builder function. */
  static dynamicColor<Required extends boolean, OuterType = unknown>(
    getA: LazyBuild<
      {
@@ -659,6 +680,7 @@ export class Value<
      validator,
    )
  }
+  /** Like {@link Value.datetime} but options are resolved lazily at runtime via a builder function. */
  static dynamicDatetime<Required extends boolean, OuterType = unknown>(
    getA: LazyBuild<
      {
@@ -769,6 +791,7 @@ export class Value<
      validator,
    )
  }
+  /** Like {@link Value.select} but options are resolved lazily at runtime via a builder function. */
  static dynamicSelect<
    Values extends Record<string, string>,
    OuterType = unknown,
@@ -889,6 +912,7 @@ export class Value<
      validator,
    )
  }
+  /** Like {@link Value.multiselect} but options are resolved lazily at runtime via a builder function. */
  static dynamicMultiselect<
    Values extends Record<string, string>,
    OuterType = unknown,
@@ -977,6 +1001,12 @@ export class Value<
      }
    }, spec.validator)
  }
+  /**
+   * Displays a file upload input field.
+   *
+   * @param a.extensions - Allowed file extensions (e.g. `[".pem", ".crt"]`)
+   * @param a.required - Whether a file must be selected
+   */
  static file<Required extends boolean>(a: {
    name: string
    description?: string | null
@@ -1000,6 +1030,7 @@ export class Value<
      asRequiredParser(fileInfoParser, a),
    )
  }
+  /** Like {@link Value.file} but options are resolved lazily at runtime via a builder function. */
  static dynamicFile<Required extends boolean, OuterType = unknown>(
    a: LazyBuild<
      {
@@ -1102,6 +1133,7 @@ export class Value<
      }
    }, a.variants.validator)
  }
+  /** Like {@link Value.union} but options (including which variants are available) are resolved lazily at runtime. */
  static dynamicUnion<
    VariantValues extends {
      [K in string]: {
@@ -1123,6 +1155,7 @@ export class Value<
      OuterType
    >,
  ): Value<UnionRes<VariantValues>, UnionRes<VariantValues>, OuterType>
+  /** Like {@link Value.union} but options are resolved lazily, with an explicit static validator type. */
  static dynamicUnion<
    StaticVariantValues extends {
      [K in string]: {
@@ -1300,6 +1333,12 @@ export class Value<
    }, z.any())
  }

+  /**
+   * Transforms the validated output value using a mapping function.
+   * The form field itself remains unchanged, but the value is transformed after validation.
+   *
+   * @param fn - A function to transform the validated value
+   */
  map<U>(fn: (value: StaticValidatedAs) => U): Value<U, U, OuterType> {
    return new Value<U, U, OuterType>(async (options) => {
      const built = await this.build(options)
--- a/sdk/base/lib/actions/input/builder/variants.ts
+++ b/sdk/base/lib/actions/input/builder/variants.ts
@@ -8,6 +8,11 @@ import {
 } from './inputSpec'
 import { z } from 'zod'

+/**
+ * The runtime result type of a discriminated union form field.
+ * Contains `selection` (the chosen variant key), `value` (the variant's form data),
+ * and optionally `other` (partial data from previously selected variants).
+ */
 export type UnionRes<
  VariantValues extends {
    [K in string]: {
@@ -28,6 +33,7 @@ export type UnionRes<
  }
 }[K]

+/** Like {@link UnionRes} but using the static (Zod-inferred) validated types. */
 export type UnionResStaticValidatedAs<
  VariantValues extends {
    [K in string]: {
@@ -118,6 +124,11 @@ export class Variants<
    >,
  ) {}
  readonly _TYPE: UnionRes<VariantValues> = null as any
+  /**
+   * Creates a `Variants` instance from a record mapping variant keys to their display name and form spec.
+   *
+   * @param a - A record of `{ name: string, spec: InputSpec }` entries, one per variant
+   */
  static of<
    VariantValues extends {
      [K in string]: {