ShiboSoftwareDev/cc2340r5-reference-design

A CC2340R5 wireless MCU reference board integrating a 2.4 GHz RF matching network and antenna, 48 MHz/optional 32.768 kHz crystals, DC/DC inductors, decoupling capacitors, reset circuitry, power input, and SWD debug connector.

Version
1.4.0
License
unset
Stars
0

scripts/shared/package-props-schema.ts

/** The package's published JSON Schema is the only source of parameter domains. */
export type ParameterValue = boolean | number | string
export type PackagePropsSchema = {
  $ref?: string
  type?: string | readonly string[]
  properties?: Record<string, PackagePropsSchema>
  enum?: readonly unknown[]
  const?: unknown
  default?: unknown
  title?: string
  minimum?: number
  maximum?: number
  exclusiveMinimum?: number
  exclusiveMaximum?: number
  multipleOf?: number
  readOnly?: boolean
  anyOf?: readonly PackagePropsSchema[]
  oneOf?: readonly PackagePropsSchema[]
  [key: string]: unknown
}
type Base = { id: string; label: string; default: ParameterValue }
export type SchemaParameter =
  | (Base & { type: "boolean"; default: boolean })
  | (Base & {
      type: "number"
      unit: string
      options: { value: ParameterValue; number: number }[]
    })
  | (Base & {
      type: "enum"
      options: { value: ParameterValue; label: string }[]
    })

const scalar = (value: unknown): value is ParameterValue =>
  typeof value === "boolean" ||
  typeof value === "string" ||
  (typeof value === "number" && Number.isFinite(value))
const own = (value: object, key: string) =>
  Object.prototype.hasOwnProperty.call(value, key)
const fail = (id: string, message: string): never => {
  throw new Error(`Parameter ${id}: ${message}`)
}
const resolve = (
  root: PackagePropsSchema,
  input: PackagePropsSchema,
  seen = new Set<string>(),
): PackagePropsSchema => {
  if (!input || typeof input !== "object" || Array.isArray(input))
    throw new Error("Invalid package props schema")
  if (!input.$ref) return input
  const ref = input.$ref
  if (!ref.startsWith("#/") || seen.has(ref))
    throw new Error("Only nonrecursive local schema references are supported")
  seen.add(ref)
  let target: any = root
  for (const part of ref.slice(2).split("/")) {
    const key = part.replace(/~1/g, "/").replace(/~0/g, "~")
    if (!target || !own(target, key))
      throw new Error(`Missing schema reference ${ref}`)
    target = target[key]
  }
  const { $ref: _, ...annotations } = input
  return { ...resolve(root, target, seen), ...annotations }
}

function domain(
  root: PackagePropsSchema,
  input: PackagePropsSchema,
  id: string,
): ParameterValue[] {
  const field = resolve(root, input)
  if (
    ["allOf", "if", "then", "else", "not", "dependentSchemas"].some((key) =>
      own(field, key),
    )
  )
    return fail(
      id,
      "conditional domains are not supported by prebuilt previews",
    )
  let values: unknown[]
  if (own(field, "const")) values = [field.const]
  else if (field.readOnly && own(field, "default")) values = [field.default]
  else if (field.enum) values = [...field.enum]
  else if (field.anyOf || field.oneOf)
    values = (field.anyOf ?? field.oneOf)!.flatMap((option) =>
      domain(root, option, id),
    )
  else if (field.type === "boolean") values = [false, true]
  else if (field.type === "number" || field.type === "integer") {
    const minimum = field.minimum ?? field.exclusiveMinimum
    const maximum = field.maximum ?? field.exclusiveMaximum
    const step = field.multipleOf ?? (field.type === "integer" ? 1 : undefined)
    if (
      !Number.isFinite(minimum) ||
      !Number.isFinite(maximum) ||
      !step ||
      !Number.isFinite(step) ||
      step <= 0
    )
      return fail(
        id,
        "declare enum values, or finite bounds and multipleOf (step)",
      )
    const epsilon = Math.abs(step) * 1e-9
    const start = Math.ceil((minimum! - epsilon) / step) * step
    const count = Math.floor((maximum! - start + epsilon) / step) + 1
    if (count < 1 || count > 128)
      return fail(id, "the supported range must contain 1–128 steps")
    values = Array.from({ length: count }, (_, index) =>
      Number((start + index * step).toPrecision(14)),
    ).filter(
      (value) =>
        (field.type !== "integer" || Number.isInteger(value)) &&
        (field.exclusiveMinimum === undefined ||
          value > field.exclusiveMinimum + epsilon) &&
        (field.exclusiveMaximum === undefined ||
          value < field.exclusiveMaximum - epsilon),
    )
  } else
    return fail(id, "declare a finite boolean, enum, or bounded numeric domain")
  if (!values.length || values.length > 128 || !values.every(scalar))
    return fail(id, "supported choices must be finite scalar values")
  for (const value of values) {
    const types = Array.isArray(field.type)
      ? field.type
      : field.type
        ? [field.type]
        : []
    if (
      types.length &&
      !types.some(
        (type) =>
          type === typeof value ||
          (type === "integer" &&
            typeof value === "number" &&
            Number.isInteger(value)),
      )
    )
      return fail(id, "a choice does not match the declared type")
    if (
      typeof value === "number" &&
      ((field.minimum !== undefined && value < field.minimum) ||
        (field.maximum !== undefined && value > field.maximum) ||
        (field.exclusiveMinimum !== undefined &&
          value <= field.exclusiveMinimum) ||
        (field.exclusiveMaximum !== undefined &&
          value >= field.exclusiveMaximum) ||
        (field.multipleOf !== undefined &&
          Math.abs(
            value / field.multipleOf - Math.round(value / field.multipleOf),
          ) > 1e-8))
    )
      return fail(id, "a choice violates the numeric bounds")
  }
  const unique = [...new Set(values as ParameterValue[])]
  if (unique.length !== values.length) return fail(id, "duplicate choices")
  return unique
}

const prefixes: Record<string, number> = {
  y: 1e-24,
  z: 1e-21,
  a: 1e-18,
  f: 1e-15,
  p: 1e-12,
  n: 1e-9,
  u: 1e-6,
  µ: 1e-6,
  μ: 1e-6,
  m: 1e-3,
  "": 1,
  k: 1e3,
  M: 1e6,
  G: 1e9,
  T: 1e12,
  P: 1e15,
  E: 1e18,
  Z: 1e21,
  Y: 1e24,
}
const engineering: Record<number, string> = {
  [-24]: "y",
  [-21]: "z",
  [-18]: "a",
  [-15]: "f",
  [-12]: "p",
  [-9]: "n",
  [-6]: "µ",
  [-3]: "m",
  0: "",
  3: "k",
  6: "M",
  9: "G",
  12: "T",
  15: "P",
  18: "E",
  21: "Z",
  24: "Y",
}
const normalizeUnit = (unit: string) => (/^ohms?$/i.test(unit) ? "Ω" : unit)
function quantity(value: ParameterValue, hint: string) {
  if (typeof value === "number") return { number: value, unit: hint }
  if (typeof value !== "string") return undefined
  const match = value
    .trim()
    .match(
      /^([+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?)\s*([yzafpnuµμmkMGTPEZY]?)([A-Za-zΩ%°]*)$/,
    )
  if (!match) return undefined
  const unit = normalizeUnit(match[3] || hint)
  if (hint && unit !== hint) return undefined
  const number = Number(match[1]) * prefixes[match[2]]
  return Number.isFinite(number) ? { number, unit } : undefined
}
const humanize = (id: string) => {
  const words = id.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ")
  return words.charAt(0).toUpperCase() + words.slice(1).toLowerCase()
}

export function derivePackageParameters(schema: PackagePropsSchema) {
  const root = resolve(schema, schema)
  if (root.type !== "object" || !root.properties)
    throw new Error("Package props schema must describe an object")
  if (
    [
      "allOf",
      "anyOf",
      "oneOf",
      "if",
      "then",
      "else",
      "not",
      "dependentSchemas",
      "dependencies",
    ].some((key) => own(root, key))
  )
    throw new Error(
      "Conditional object schemas are not supported by prebuilt previews",
    )
  const entries = Object.entries(root.properties)
  if (entries.length > 16)
    throw new Error("Package preview supports up to 16 properties")
  const defaults: Record<string, ParameterValue> = {}
  const domains: Record<string, ParameterValue[]> = {}
  const parameters: SchemaParameter[] = []
  for (const [id, input] of entries) {
    if (!/^[a-zA-Z][a-zA-Z0-9_]*$/.test(id))
      return fail(id, "unsupported property name")
    const field = resolve(schema, input)
    const values = domain(schema, field, id)
    const rootDefault = root.default as Record<string, unknown> | undefined
    const defaultValue = own(field, "default")
      ? field.default
      : rootDefault && own(rootDefault, id)
        ? rootDefault[id]
        : values.length === 1
          ? values[0]
          : undefined
    if (!scalar(defaultValue) || !values.includes(defaultValue))
      return fail(id, "a valid schema default is required")
    defaults[id] = defaultValue
    domains[id] = values
    if (values.length < 2 || field.readOnly) continue
    const label = field.title?.trim() || humanize(id)
    if (label.length > 120) return fail(id, "title is too long")
    if (values.every((value) => typeof value === "boolean")) {
      parameters.push({
        id,
        label,
        default: defaultValue as boolean,
        type: "boolean",
      })
      continue
    }
    const unitHint =
      typeof field["x-unit"] === "string" ? normalizeUnit(field["x-unit"]) : ""
    const quantities = values.map((value) => quantity(value, unitHint))
    if (
      quantities.every(Boolean) &&
      new Set(quantities.map((value) => value!.unit)).size === 1
    ) {
      const unit = quantities[0]!.unit
      const largest = Math.max(
        ...quantities.map((value) => Math.abs(value!.number)),
      )
      const exponent =
        unit && largest
          ? Math.max(-24, Math.min(24, Math.floor(Math.log10(largest) / 3) * 3))
          : 0
      const scale = 10 ** exponent
      const options = values
        .map((value, index) => ({
          value,
          number: Number((quantities[index]!.number / scale).toPrecision(12)),
        }))
        .sort((a, b) => a.number - b.number)
      if (
        new Set(options.map((option) => option.number)).size !== options.length
      )
        return fail(id, "quantity choices must have distinct numeric values")
      parameters.push({
        id,
        label,
        default: defaultValue,
        type: "number",
        unit: `${engineering[exponent]}${unit}`,
        options,
      })
    } else {
      parameters.push({
        id,
        label,
        default: defaultValue,
        type: "enum",
        options: values.map((value) => ({ value, label: String(value) })),
      })
    }
  }
  return { parameters, defaults, domains }
}

/** Enumerate exact supported states without a package-specific field list. */
export function enumeratePackageStates(
  schema: PackagePropsSchema,
  maxStates = 256,
) {
  const definition = derivePackageParameters(schema)
  let states: Record<string, ParameterValue>[] = [{}]
  for (const [id, values] of Object.entries(definition.domains)) {
    if (states.length * values.length > maxStates)
      throw new Error(
        `Package preview exceeds ${maxStates} combinations; narrow the schema's supported domain`,
      )
    states = states.flatMap((state) =>
      values.map((value) => ({ ...state, [id]: value })),
    )
  }
  return { ...definition, states }
}