fixup! WIP

src/declaration.ts

@@ -1,4 +1,3 @@
-import type { Example } from "./example.js";
 import { definedValue, Maybe, undefinedValue } from "./maybe.js";
 
 export type Declaration<T, O extends Options<unknown>> = {
@@ -12,7 +11,6 @@ export type Value<
 
 export type Options<T> = {
   readonly default?: T;
-  readonly examples?: Example[];
   readonly isSensitive?: boolean;
 };
 

src/declaration/big-integer.ts

@@ -12,12 +12,17 @@ import {
 } from "../declaration.js";
 import { registerVariable } from "../environment.js";
 import { normalize } from "../error.js";
-import { type Example } from "../example.js";
+import {
+  marshalExamples,
+  type DeclarationExampleOptions,
+  type VariableExample,
+} from "../example.js";
 import { resolve } from "../maybe.js";
 import { ScalarSchema, createScalar, toString } from "../schema.js";
 import { SpecError } from "../variable.js";
 
 export type Options = DeclarationOptions<bigint> &
+  DeclarationExampleOptions<bigint> &
   Partial<RangeConstraintSpec<bigint>>;
 
 export function bigInteger<O extends Options>(
@@ -36,7 +41,7 @@ export function bigInteger<O extends Options>(
     default: def,
     isSensitive,
     schema,
-    examples: examples ?? buildExamples(),
+    examples: examples ? marshalExamples(schema, examples) : buildExamples(),
   });
 
   return {
@@ -68,7 +73,7 @@ function createSchema(name: string, options: Options): ScalarSchema<bigint> {
   return createScalar("big integer", toString, unmarshal, constraints);
 }
 
-function buildExamples(): Example[] {
+function buildExamples(): VariableExample[] {
   return [
     {
       value: "123456",

src/declaration/binary.ts

@@ -12,7 +12,11 @@ import {
 } from "../declaration.js";
 import { registerVariable } from "../environment.js";
 import { normalize } from "../error.js";
-import { type Example } from "../example.js";
+import {
+  marshalExamples,
+  type DeclarationExampleOptions,
+  type VariableExample,
+} from "../example.js";
 import { resolve } from "../maybe.js";
 import { ScalarSchema, createScalar } from "../schema.js";
 import { SpecError } from "../variable.js";
@@ -22,10 +26,11 @@ const PATTERNS: Partial<Record<BufferEncoding, RegExp>> = {
   hex: /^[0-9a-fA-F]*$/,
 } as const;
 
-export type Options = DeclarationOptions<Buffer> & {
-  readonly encoding?: BufferEncoding;
-  readonly length?: LengthConstraintSpec;
-};
+export type Options = DeclarationOptions<Buffer> &
+  DeclarationExampleOptions<Buffer> & {
+    readonly encoding?: BufferEncoding;
+    readonly length?: LengthConstraintSpec;
+  };
 
 export function binary<O extends Options>(
   name: string,
@@ -48,7 +53,9 @@ export function binary<O extends Options>(
     default: def,
     isSensitive,
     schema,
-    examples: examples ?? buildExamples(encoding, schema),
+    examples: examples
+      ? marshalExamples(schema, examples)
+      : buildExamples(encoding, schema),
   });
 
   return {
@@ -105,7 +112,7 @@ function createUnmarshal(
 function buildExamples(
   encoding: BufferEncoding,
   schema: ScalarSchema<Buffer>,
-): Example[] {
+): VariableExample[] {
   return [
     {
       value: schema.marshal(Buffer.from("conquistador", "utf-8")),

src/declaration/boolean.ts

@@ -6,14 +6,19 @@ import {
   type ExactOptions,
 } from "../declaration.js";
 import { registerVariable } from "../environment.js";
-import { type Example } from "../example.js";
+import {
+  marshalExamples,
+  type DeclarationExampleOptions,
+  type VariableExample,
+} from "../example.js";
 import { resolve } from "../maybe.js";
 import { EnumSchema, InvalidEnumError, createEnum } from "../schema.js";
 import { SpecError } from "../variable.js";
 
-export type Options = DeclarationOptions<boolean> & {
-  readonly literals?: Literals;
-};
+export type Options = DeclarationOptions<boolean> &
+  DeclarationExampleOptions<boolean> & {
+    readonly literals?: Literals;
+  };
 
 export type Literals = Record<string, boolean>;
 
@@ -38,7 +43,9 @@ export function boolean<O extends Options>(
     default: def,
     isSensitive,
     schema,
-    examples: examples ?? buildExamples(literals),
+    examples: examples
+      ? marshalExamples(schema, examples)
+      : buildExamples(literals),
   });
 
   return {
@@ -83,7 +90,7 @@ function findLiteral(
   throw new MissingLiteralError(name, native);
 }
 
-function buildExamples(literals: Literals): Example[] {
+function buildExamples(literals: Literals): VariableExample[] {
   return Object.entries(literals).map(([literal, native]) => ({
     value: literal,
     description: String(native),

src/declaration/duration.ts

@@ -13,7 +13,11 @@ import {
 } from "../declaration.js";
 import { registerVariable } from "../environment.js";
 import { normalize } from "../error.js";
-import { type Example } from "../example.js";
+import {
+  marshalExamples,
+  type DeclarationExampleOptions,
+  type VariableExample,
+} from "../example.js";
 import { resolve } from "../maybe.js";
 import { ScalarSchema, createScalar, toString } from "../schema.js";
 import { SpecError } from "../variable.js";
@@ -22,6 +26,7 @@ const { Duration } = Temporal;
 type Duration = Temporal.Duration;
 
 export type Options = DeclarationOptions<Duration> &
+  DeclarationExampleOptions<Duration> &
   Partial<RangeConstraintSpec<Duration>>;
 
 export function duration<O extends Options>(
@@ -40,7 +45,7 @@ export function duration<O extends Options>(
     default: def,
     isSensitive,
     schema,
-    examples: examples ?? buildExamples(),
+    examples: examples ? marshalExamples(schema, examples) : buildExamples(),
   });
 
   return {
@@ -72,7 +77,7 @@ function createSchema(name: string, options: Options): ScalarSchema<Duration> {
   return createScalar("ISO 8601 duration", toString, unmarshal, constraints);
 }
 
-function buildExamples(): Example[] {
+function buildExamples(): VariableExample[] {
   return [
     {
       value: Duration.from({ minutes: 1, seconds: 30 }).toString(),

src/declaration/enumeration.ts

@@ -6,7 +6,11 @@ import {
   type ExactOptions,
 } from "../declaration.js";
 import { registerVariable } from "../environment.js";
-import { type Example } from "../example.js";
+import {
+  marshalExamples,
+  type DeclarationExampleOptions,
+  type VariableExample,
+} from "../example.js";
 import { resolve } from "../maybe.js";
 import { EnumSchema, InvalidEnumError, createEnum } from "../schema.js";
 import { SpecError } from "../variable.js";
@@ -18,7 +22,7 @@ export type Member<T> = {
   readonly description: string;
 };
 
-export type Options<T> = DeclarationOptions<T>;
+export type Options<T> = DeclarationOptions<T> & DeclarationExampleOptions<T>;
 
 export function enumeration<T, O extends Options<T>>(
   name: string,
@@ -37,7 +41,9 @@ export function enumeration<T, O extends Options<T>>(
     default: def,
     isSensitive,
     schema,
-    examples: examples ?? buildExamples(members),
+    examples: examples
+      ? marshalExamples(schema, examples)
+      : buildExamples(members),
   });
 
   return {
@@ -75,7 +81,7 @@ function createSchema<T>(name: string, members: Members<T>): EnumSchema<T> {
   return createEnum(schemaMembers, marshal, unmarshal, []);
 }
 
-function buildExamples<T>(members: Members<T>): Example[] {
+function buildExamples<T>(members: Members<T>): VariableExample[] {
   return Object.entries(members).map(([literal, { description }]) => ({
     value: literal,
     description,

src/declaration/integer.ts

@@ -14,12 +14,17 @@ import {
 } from "../declaration.js";
 import { registerVariable } from "../environment.js";
 import { normalize } from "../error.js";
-import { type Example } from "../example.js";
+import {
+  marshalExamples,
+  type DeclarationExampleOptions,
+  type VariableExample,
+} from "../example.js";
 import { resolve } from "../maybe.js";
 import { ScalarSchema, createScalar, toString } from "../schema.js";
 import { SpecError } from "../variable.js";
 
 export type Options = DeclarationOptions<number> &
+  DeclarationExampleOptions<number> &
   Partial<RangeConstraintSpec<number>>;
 
 export function integer<O extends Options>(
@@ -38,7 +43,7 @@ export function integer<O extends Options>(
     default: def,
     isSensitive,
     schema,
-    examples: examples ?? buildExamples(),
+    examples: examples ? marshalExamples(schema, examples) : buildExamples(),
   });
 
   return {
@@ -67,7 +72,7 @@ function createSchema(name: string, options: Options): ScalarSchema<number> {
   return createScalar("integer", toString, unmarshal, constraints);
 }
 
-function buildExamples(): Example[] {
+function buildExamples(): VariableExample[] {
   return [
     {
       value: "123456",

src/declaration/kubernetes-address.ts

@@ -9,7 +9,10 @@ import {
 } from "../declaration.js";
 import { registerVariable } from "../environment.js";
 import { normalize } from "../error.js";
-import { type Example } from "../example.js";
+import {
+  type DeclarationExampleOptions,
+  type VariableExample,
+} from "../example.js";
 import { Maybe, map, resolve } from "../maybe.js";
 import {
   ScalarSchema,
@@ -24,9 +27,10 @@ export type KubernetesAddress = {
   readonly port: number;
 };
 
-export type Options = DeclarationOptions<KubernetesAddress> & {
-  readonly portName?: string;
-};
+export type Options = DeclarationOptions<KubernetesAddress> &
+  DeclarationExampleOptions<KubernetesAddress> & {
+    readonly portName?: string;
+  };
 
 export function kubernetesAddress<O extends Options>(
   name: string,
@@ -80,7 +84,7 @@ function registerHost(
   });
 }
 
-function buildHostExamples(): Example[] {
+function buildHostExamples(): VariableExample[] {
   return [
     {
       value: "service.example.org",
@@ -146,7 +150,7 @@ function createPortSchema(): ScalarSchema<number> {
   ]);
 }
 
-function buildPortExamples(): Example[] {
+function buildPortExamples(): VariableExample[] {
   return [
     {
       value: "12345",

src/declaration/network-port-number.ts

@@ -14,12 +14,17 @@ import {
 } from "../declaration.js";
 import { registerVariable } from "../environment.js";
 import { normalize } from "../error.js";
-import { type Example } from "../example.js";
+import {
+  marshalExamples,
+  type DeclarationExampleOptions,
+  type VariableExample,
+} from "../example.js";
 import { resolve } from "../maybe.js";
 import { ScalarSchema, createScalar, toString } from "../schema.js";
 import { SpecError } from "../variable.js";
 
 export type Options = DeclarationOptions<number> &
+  DeclarationExampleOptions<number> &
   Partial<RangeConstraintSpec<number>>;
 
 export function networkPortNumber<O extends Options>(
@@ -38,7 +43,7 @@ export function networkPortNumber<O extends Options>(
     default: def,
     isSensitive,
     schema,
-    examples: examples ?? buildExamples(),
+    examples: examples ? marshalExamples(schema, examples) : buildExamples(),
   });
 
   return {
@@ -72,7 +77,7 @@ function createSchema(name: string, options: Options): ScalarSchema<number> {
   return createScalar("port number", toString, unmarshal, constraints);
 }
 
-function buildExamples(): Example[] {
+function buildExamples(): VariableExample[] {
   return [
     {
       value: "12345",

src/declaration/number.ts

@@ -12,12 +12,17 @@ import {
 } from "../declaration.js";
 import { registerVariable } from "../environment.js";
 import { normalize } from "../error.js";
-import { type Example } from "../example.js";
+import {
+  marshalExamples,
+  type DeclarationExampleOptions,
+  type VariableExample,
+} from "../example.js";
 import { resolve } from "../maybe.js";
 import { ScalarSchema, createScalar, toString } from "../schema.js";
 import { SpecError } from "../variable.js";
 
 export type Options = DeclarationOptions<number> &
+  DeclarationExampleOptions<number> &
   Partial<RangeConstraintSpec<number>>;
 
 export function number<O extends Options>(
@@ -36,7 +41,7 @@ export function number<O extends Options>(
     default: def,
     isSensitive,
     schema,
-    examples: examples ?? buildExamples(),
+    examples: examples ? marshalExamples(schema, examples) : buildExamples(),
   });
 
   return {
@@ -68,7 +73,7 @@ function createSchema(name: string, options: Options): ScalarSchema<number> {
   return createScalar("number", toString, unmarshal, constraints);
 }
 
-function buildExamples(): Example[] {
+function buildExamples(): VariableExample[] {
   return [
     {
       value: "123456",