Paka.Exports

Paka / Exports

Import

Namespace

import { Paka } from '@wollybeard/kit'

Barrel

import * as Paka from '@wollybeard/kit/paka'

Namespaces

• Adaptors
• Extractor

Constants

[C] ExportLevel

Enums<{ readonly value: 'value'; readonly type: 'type' }>

Source

Export level distinguishes between runtime values and type-only exports.

[C] ValueExportType

Enums<
  {
    readonly function: 'function'
    readonly const: 'const'
    readonly class: 'class'
    readonly namespace: 'namespace'
  }
>

Source

Value export types

• exports that exist at runtime.

[C] TypeExportType

Enums<
  {
    readonly interface: 'interface'
    readonly 'type-alias': 'type-alias'
    readonly enum: 'enum'
    readonly union: 'union'
    readonly intersection: 'intersection'
  }
>

Source

Type export types

• exports that only exist in TypeScript's type system.

[C] BuilderMethodCategory

Enums<
  {
    readonly chainable: 'chainable'
    readonly terminal: 'terminal'
    readonly transform: 'transform'
  }
>

Source

Builder method classification based on return type.

• chainable
• Returns the same builder type (for method chaining)
• terminal
• Returns void (ends the builder chain)
• transform
• Returns a different builder type (transforms to another builder)

[C] SignatureModel

Union<
  [
    typeof FunctionSignatureModel,
    typeof BuilderSignatureModel,
    typeof ClassSignatureModel,
    typeof TypeSignatureModel,
    typeof ValueSignatureModel,
  ]
>

Source

Signature model

• tagged union of all signature types.

Discriminated by _tag field:

• FunctionSignatureModel
• Functions with structured overloads
• BuilderSignatureModel
• Builder pattern APIs with chainable/terminal methods
• ClassSignatureModel
• Classes with constructor, properties, methods
• TypeSignatureModel
• Types, interfaces, type aliases (text)
• ValueSignatureModel
• Const values (type as text)

[C] Module

Schema<Module, ModuleEncoded, never>

Source

Module schema

• uses suspend for circular reference with ValueExport.

NOTE: The as any assertions are required here due to circular dependency:

• Module contains Export[] (through exports field)
• ValueExport (part of Export union) contains optional Module (through module field)

Effect Schema's S.suspend handles this at runtime, but TypeScript needs help with the circular type reference. The interface definitions above ensure type safety for consumers.

[C] Export

Union<[typeof ValueExport, typeof TypeExport]>

Source

Export is a tagged union of value and type exports.

[C] Entrypoint

Union<[typeof DrillableNamespaceEntrypoint, typeof SimpleEntrypoint]>

Source

Entrypoint union

• all patterns.

[C] InterfaceModel

typeof Package

Source

The complete interface model output.

Classes

[Class] Example

class {
}

Source

Code example extracted from JSDoc

[Class] SourceLocation

class {
}

Source

Source location for "View source" links.

[Class] TypeParameter

class {
}

Source

Type parameter for generic functions/classes. Captures type parameter name, constraint, and default value.

Examples:

// <T extends string = 'default'>
{ name: 'T', constraint: 'string', default: "'default'" }

[Class] Parameter

class {
}

Source

Function/method parameter. Captures parameter name, type, modifiers, and JSDoc description.

Examples:

import { Paka } from '@wollybeard/kit/paka' // ---cut---
 // (items: T[], fn?: (item: T) => U, ...rest: unknown[])
;[
  {
    name: 'items',
    type: 'T[]',
    optional: false,
    rest: false,
    description: 'Array of items to process',
  },
  {
    name: 'fn',
    type: '(item: T) => U',
    optional: true,
    rest: false,
    description: 'Transform function',
  },
  { name: 'rest', type: 'unknown[]', optional: false, rest: true },
]

[Class] FunctionSignature

class {
}

Source

Single function signature (one overload). Captures type parameters, parameters, return type, and JSDoc documentation.

Used within FunctionSignatureModel to support multiple overloads.

Examples:

{
  typeParameters: [{ name: 'T', constraint: 'string' }],
    parameters: [{ name: 'value', type: 'T', description: 'Input value' }],
      returnType: 'T',
        returnDoc: 'The processed value',
          throws: ['Error if value is invalid']
}

[Class] FunctionSignatureModel

class {
}

Source

Function signature model supporting multiple overloads.

Structured representation of function signatures with full parameter, type parameter, and return type information.

Examples:

// function parse(input: string): Config
// function parse(input: Buffer): Config
{
  _tag: 'FunctionSignatureModel',
    overloads: [
      { typeParameters: [], parameters: [{ name: 'input', type: 'string', ... }], returnType: 'Config' },
      { typeParameters: [], parameters: [{ name: 'input', type: 'Buffer', ... }], returnType: 'Config' }
    ]
}

[Class] BuilderMethod

class {
}

Source

Builder method on a builder interface.

Captures method name, overloads, and classification based on return type. Methods are classified during extraction by analyzing their return types.

Examples:

// inputType<I>(): TestBuilder<State & { input: I }>
{
  name: 'inputType',
    overloads: [...],
      category: 'chainable',
        transformsTo: undefined
}

// test(): void
{
  name: 'test',
    overloads: [...],
      category: 'terminal',
        transformsTo: undefined
}

// layer<R>(layer: any): OtherBuilder<State, R>
{
  name: 'layer',
    overloads: [...],
      category: 'transform',
        transformsTo: 'OtherBuilder'
}

[Class] BuilderSignatureModel

class {
}

Source

Builder signature model for fluent/builder pattern APIs.

Builder patterns are detected when a function is marked with @builder JSDoc tag. The extractor automatically crawls the returned builder type interface and classifies methods based on their return types:

• Chainable: Returns the same builder type (enables method chaining)
• Terminal: Returns void (ends the builder chain)
• Transform: Returns a different builder type (transforms to another builder)

Examples:

Extracted as:

{
  _tag: 'BuilderSignatureModel',
    typeName: 'TestBuilder',
      entryPoint: FunctionSignature { ... },
  chainableMethods: [
    { name: 'inputType', category: 'chainable', ... },
    { name: 'cases', category: 'chainable', ... }
  ],
    terminalMethods: [
      { name: 'test', category: 'terminal', overloads: [...2 overloads] }
    ],
      transformMethods: [
        { name: 'layer', category: 'transform', transformsTo: 'OtherBuilder', ... }
      ]
}

[Class] TypeSignatureModel

class {
}

Source

Type signature model (interfaces, type aliases, etc).

For now, these are kept as plain text since parsing TypeScript type definitions into structured form is complex with diminishing returns.

Future: Could be expanded to structured form (properties, methods, etc).

[Class] ValueSignatureModel

class {
}

Source

Value signature model (simple const values, primitives).

Used for exports that are simple constant values (not functions/classes). Stores the inferred type as text.

Examples:

// export const PI = 3.14159
{ _tag: 'ValueSignatureModel', type: 'number' }

[Class] ClassProperty

class {
}

Source

Class property. Captures property name, type, modifiers, and JSDoc description.

Examples:

import { Paka } from '@wollybeard/kit/paka' // ---cut---
 // class User {
//   readonly id: string
//   name?: string
//   static count: number
// }
;[
  {
    name: 'id',
    type: 'string',
    optional: false,
    readonly: true,
    static: false,
  },
  {
    name: 'name',
    type: 'string',
    optional: true,
    readonly: false,
    static: false,
  },
  {
    name: 'count',
    type: 'number',
    optional: false,
    readonly: false,
    static: true,
  },
]

[Class] ClassMethod

class {
}

Source

Class method. Captures method name, overloads, and modifiers.

Examples:

// class User {
//   getName(): string
//   static create(name: string): User
// }
[
  { name: 'getName', overloads: [...], static: false },
  { name: 'create', overloads: [...], static: true }
]

[Class] ClassSignatureModel

class {
}

Source

Class signature model with structured class information.

Structured representation of class with constructor, properties, and methods.

Examples:

// export class User {
//   readonly id: string
//   name: string
//   constructor(id: string, name: string) { ... }
//   getName(): string { return this.name }
//   static create(name: string): User { return new User(crypto.randomUUID(), name) }
// }
{
  _tag: 'ClassSignatureModel',
    ctor: { typeParameters: [], parameters: [...], returnType: 'User' },
  properties: [
    { name: 'id', type: 'string', readonly: true, ... },
    { name: 'name', type: 'string', readonly: false, ... }
  ],
    methods: [
      { name: 'getName', overloads: [...], static: false },
      { name: 'create', overloads: [...], static: true }
    ]
}

[Class] ValueExport

class {
}

Source

Value export

• represents a runtime export. Namespace exports include a nested module.

[Class] TypeExport

class {
}

Source

Type export

• represents a type-only export.

[Class] DrillableNamespaceEntrypoint

class {
}

Source

Drillable Namespace Pattern entrypoint.

This pattern is detected ONLY for the main entrypoint ('.') when ALL conditions are met:

1. The main entrypoint source file contains a namespace export: export * as Name from './path' 2. The namespace name (PascalCase, e.g., A) converts to kebab-case (e.g., a) 3. A subpath export exists in package.json with that kebab name (e.g., ./a) 4. The file that the namespace export points to 5. AND the file that the subpath export points to 6. Must resolve to the SAME source file

When detected, this enables two import forms:

• import { Name } from 'package'
• imports the namespace from main entrypoint
• import * as Name from 'package/kebab-name'
• imports the barrel directly

Examples:

Both the namespace export and the subpath export resolve to src/a.ts → Drillable!

// package.json
{
  "exports": {
    ".": "./build/index.js",
      "./a": "./build/a.js"
  }
}

// src/index.ts (main entrypoint)
export * as A from './a.js'

// src/a.ts (barrel implementation)
export const foo = () => { }

Non-drillable case - different files

// package.json
{
  "exports": {
    ".": "./build/index.js",
      "./a": "./build/a.js"
  }
}

// src/index.ts
export * as A from './z.js'  // ← Points to z.js, not a.js

// Namespace points to src/z.ts, subpath points to src/a.ts → NOT drillable (different files)

[Class] SimpleEntrypoint

class {
}

Source

Simple entrypoint without special import pattern.

[Class] PackageMetadata

class {
}

Source

Package metadata.

[Class] Package

class {
}

Source

Package represents the complete extracted documentation model.

Types

[T] ExportLevel

type ExportLevel = typeof ExportLevel.Type

Source

[T] ValueExportType

type ValueExportType = typeof ValueExportType.Type

Source

[T] TypeExportType

type TypeExportType = typeof TypeExportType.Type

Source

[T] BuilderMethodCategory

type BuilderMethodCategory = typeof BuilderMethodCategory.Type

Source

[T] SignatureModel

type SignatureModel = S.Schema.Type<typeof SignatureModel>

Source

[I] Module

interface Module {
  readonly location: typeof FsLoc.RelFile.Type
  readonly description: string
  readonly descriptionSource?: 'jsdoc' | 'md-file'
  readonly category?: string
  readonly exports: ReadonlyArray<Export>
}

Source

Module type definition.

[I] ModuleEncoded

interface ModuleEncoded extends Module {}

Source

Module encoded type (same as Module since no transformations).

[T] Export

type Export = S.Schema.Type<typeof Export>

Source

[T] Entrypoint

type Entrypoint = S.Schema.Type<typeof Entrypoint>

Source

[T] InterfaceModel

type InterfaceModel = S.Schema.Type<typeof InterfaceModel>

Source