feat: rework docs api (#166)

codecs/documented.ts

@@ -0,0 +1,8 @@
+import { Codec, metadata, withMetadata } from "../common/mod.ts"
+
+export function documented<I, O>(docs: string, inner: Codec<I, O>): Codec<I, O> {
+  return withMetadata(
+    metadata("$.documented", documented, docs, inner) as never,
+    inner,
+  )
+}

codecs/mod.ts

@@ -7,6 +7,7 @@ export * from "./collections.ts"
 export * from "./compact.ts"
 export * from "./constant.ts"
 export * from "./deferred.ts"
+export * from "./documented.ts"
 export * from "./float.ts"
 export * from "./hex.ts"
 export * from "./instance.ts"

codecs/object.ts

@@ -69,13 +69,13 @@ export type OutputObject<T extends AnyCodec[]> = Expand<
 type UnionKeys<T> = T extends T ? keyof T : never
 export type ObjectMembers<T extends AnyCodec[]> = [
   ...never extends T ? {
-      [K in keyof T]:
-        AnyCodec extends T[K] ? AnyCodec :
-        & UnionKeys<Input<T[K]>>
-        & {
-          [L in keyof T]: K extends L ? never : UnionKeys<Input<T[L]>>
-        }[number] extends (infer O extends keyof any)
-        ? [O] extends [never] ? Codec<Input<T[K]> & {}> : Codec<{ [_ in O]?: never }>
+      [K in keyof T]: AnyCodec extends T[K] ? AnyCodec
+        : 
+          & UnionKeys<Input<T[K]>>
+          & {
+            [L in keyof T]: K extends L ? never : UnionKeys<Input<T[L]>>
+          }[number] extends (infer O extends keyof any)
+          ? [O] extends [never] ? Codec<Input<T[K]> & {}> : Codec<{ [_ in O]?: never }>
         : never
     }
     : T,

common/codec.ts

@@ -61,20 +61,12 @@ abstract class _Codec {
     }
     try {
       codecInspectCtx.set(this, null)
-      let content = ""
-      for (const metadata of this._metadata) {
-        if (metadata.type === "docs") {
-          // TODO: print docs in inspect
-        } else {
-          if (metadata.type === "atomic") {
-            content += metadata.name
-          } else if (metadata.type === "factory") {
-            content += `${metadata.name}(${inspect(metadata.args).replace(/^\[(?: (.+) |(.+))\]$/s, "$1$2")})`
-          }
-          break
-        }
-      }
-      content ||= "?"
+      const metadata = this._metadata[0]
+      const content = metadata
+        ? metadata.type === "atomic"
+          ? metadata.name
+          : `${metadata.name}(${inspect(metadata.args).replace(/^\[(?: (.+) |(.+))\]$/s, "$1$2")})`
+        : "?"
       id = codecInspectCtx.get(this)
       return id !== null ? `$${id} = ${content}` : content
     } finally {

common/metadata.ts

@@ -15,12 +15,6 @@ export type Metadata<I, O> = Array<
     factory: (...args: any) => Codec<I, O>
     args: any[]
   }
-  | {
-    type: "docs"
-    docs: string
-    factory?: never
-    args?: never
-  }
 >
 
 /** Metadata for an atomic codec */
@@ -38,7 +32,7 @@ export function metadata<I, O>(
     | Metadata<I, O>[]
     | [
       name: string,
-      factory?: (...args: any) => Codec<[I, O]>,
+      factory?: (...args: any) => Codec<I, O>,
       ...args: any[],
     ]
 ): Metadata<I, O> {
@@ -59,10 +53,6 @@ export function metadata<I, O>(
   ]
 }
 
-export function docs<I = any, O = any>(docs: string): Metadata<I, O> {
-  return [{ type: "docs", docs }]
-}
-
 export class CodecVisitor<R> {
   #fallback?: <I, O>(codec: Codec<I, O>) => R
   #visitors = new Map<Metadata<any, any>[number] | Function, (codec: Codec<any>, ...args: any[]) => R>()