Paka

todo

Import

NamespaceBarrel

typescript

import { Paka } from '@wollybeard/kit'

typescript

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

Constants

`[C]` `ExportLevel`

typescript

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

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

`[C]` `ValueExportType`

typescript

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

Value export types

exports that exist at runtime.

`[C]` `TypeExportType`

typescript

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

Type export types

exports that only exist in TypeScript's type system.

`[C]` `BuilderMethodCategory`

typescript

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

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]` `Provenance`

typescript

Union<[typeof JSDocProvenance, typeof MdFileProvenance]>

Union of all possible documentation provenance types.

`[C]` `SignatureModel`

typescript

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

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]` `Export`

typescript

Union<[typeof ValueExport, typeof TypeExport]>

Export is a tagged union of value and type exports.

`[C]` `Entrypoint`

typescript

Union<[typeof DrillableNamespaceEntrypoint, typeof SimpleEntrypoint]>

Entrypoint union

all patterns.

`[C]` `InterfaceModel`

typescript

typeof Package

The complete interface model output.

Classes

`[Class]` `Example`

typescript

class {
}

Code example extracted from JSDoc

`[Class]` `ImportExample`

typescript

class {
}

Import example for documentation UI.

Non-serialized class used for rendering import tabs in documentation. Returned by Entrypoint instance methods to provide structured import examples.

`[Class]` `SourceLocation`

typescript

class {
}

Source location for "View source" links.

`[Class]` `JSDocProvenance`

typescript

class {
}

Provenance for JSDoc-sourced documentation. Tracks whether it came from a shadow namespace or regular JSDoc.

`[Class]` `MdFileProvenance`

typescript

class {
}

Provenance for markdown file-sourced documentation. Includes file path for "Edit this page" links.

`[Class]` `Docs`

typescript

class {
}

Documentation content for modules and exports. Groups descriptive and guide content together.

`[Class]` `DocsProvenance`

typescript

class {
}

Provenance tracking for documentation sources. Maps each doc field (description/guide) to its source.

`[Class]` `TypeParameter`

typescript

class {
}

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

Examples:

typescript

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

`[Class]` `Parameter`

typescript

class {
}

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

Examples:

typescript

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`

typescript

class {
}

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

Used within FunctionSignatureModel to support multiple overloads.

Examples:

typescript

{
  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`

typescript

class {
}

Function signature model supporting multiple overloads.

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

Examples:

typescript

// 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`

typescript

class {
}

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:

typescript

// 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`

typescript

class {
}

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:

typescript

{
  _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`

typescript

class {
}

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`

typescript

class {
}

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:

typescript

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

`[Class]` `ClassProperty`

typescript

class {
}

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

Examples:

typescript

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`

typescript

class {
}

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

Examples:

typescript

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

`[Class]` `ClassSignatureModel`

typescript

class {
}

Class signature model with structured class information.

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

Examples:

typescript

// 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]` `Module`

typescript

class {
}

Module schema implementation.

NOTE: Circular dependency handled via declaration merging:

Module interface declared above provides type structure
Module class extends S.Class
same name enables declaration merging
Module contains Export[] (through exports field)
ValueExport (part of Export union) contains optional Module (through module field)
This is intentional and handled correctly at runtime by Effect Schema via S.suspend()

`[Class]` `ValueExport`

typescript

class {

  // Properties
  static is: (u: unknown, overrideOptions?: number | ParseOptions | undefined) => u is ValueExport
}

Value export schema implementation.

`[Class]` `TypeExport`

typescript

class {

  // Properties
  static is: (u: unknown, overrideOptions?: number | ParseOptions | undefined) => u is TypeExport
}

Type export schema implementation.

`[Class]` `DrillableNamespaceEntrypoint`

typescript

class {

  // Methods
  getImportExamples(packageName: string, breadcrumbs: string[]): ImportExample[]
}

Drillable Namespace Pattern entrypoint.

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

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!

typescript

// 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

typescript

// 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`

typescript

class {

  // Methods
  getImportExamples(packageName: string, path: string): ImportExample[]
}

Simple entrypoint without special import pattern.

`[Class]` `PackageMetadata`

typescript

class {
}

Package metadata.

`[Class]` `Package`

typescript

class {
}

Package represents the complete extracted documentation model.

Types

`[I]` `Module`

typescript

interface Module {
  readonly location: S.Schema.Type<typeof FsLoc.RelFile>
  readonly docs?: Docs | undefined
  readonly docsProvenance?: DocsProvenance | undefined
  readonly category?: string | undefined
  readonly exports: Export[]
}

Module type interface for declaration merging. Following the graphql-kit pattern for circular schemas with instance methods.

`[I]` `ValueExport`

typescript

interface ValueExport {
  readonly name: string
  readonly signature: SignatureModel
  readonly signatureSimple?: SignatureModel | undefined
  readonly docs?: Docs | undefined
  readonly docsProvenance?: DocsProvenance | undefined
  readonly examples: readonly Example[]
  readonly deprecated?: string | undefined
  readonly category?: string | undefined
  readonly tags: Readonly<Record<string, string>>
  readonly sourceLocation: SourceLocation
  readonly _tag: 'value'
  readonly type: S.Schema.Type<typeof ValueExportType>
  readonly module?: Module | undefined
}

ValueExport type interface for declaration merging.

Paka ​

Import ​

Constants ​

[C] ExportLevel ​

[C] ValueExportType ​

[C] TypeExportType ​

[C] BuilderMethodCategory ​

[C] Provenance ​

[C] SignatureModel ​

[C] Export ​

[C] Entrypoint ​

[C] InterfaceModel ​

Classes ​

[Class] Example ​

[Class] ImportExample ​

[Class] SourceLocation ​

[Class] JSDocProvenance ​

[Class] MdFileProvenance ​

[Class] Docs ​

[Class] DocsProvenance ​

[Class] TypeParameter ​

[Class] Parameter ​

[Class] FunctionSignature ​

[Class] FunctionSignatureModel ​

[Class] BuilderMethod ​

[Class] BuilderSignatureModel ​

[Class] TypeSignatureModel ​

[Class] ValueSignatureModel ​

[Class] ClassProperty ​

[Class] ClassMethod ​

[Class] ClassSignatureModel ​

[Class] Module ​

[Class] ValueExport ​

[Class] TypeExport ​

[Class] DrillableNamespaceEntrypoint ​

[Class] SimpleEntrypoint ​

[Class] PackageMetadata ​

[Class] Package ​

Types ​

[I] Module ​

[I] ValueExport ​

Paka

Import

Constants

`[C]` `ExportLevel`

`[C]` `ValueExportType`

`[C]` `TypeExportType`

`[C]` `BuilderMethodCategory`

`[C]` `Provenance`

`[C]` `SignatureModel`

`[C]` `Export`

`[C]` `Entrypoint`

`[C]` `InterfaceModel`

Classes

`[Class]` `Example`

`[Class]` `ImportExample`

`[Class]` `SourceLocation`

`[Class]` `JSDocProvenance`

`[Class]` `MdFileProvenance`

`[Class]` `Docs`

`[Class]` `DocsProvenance`

`[Class]` `TypeParameter`

`[Class]` `Parameter`

`[Class]` `FunctionSignature`

`[Class]` `FunctionSignatureModel`

`[Class]` `BuilderMethod`

`[Class]` `BuilderSignatureModel`

`[Class]` `TypeSignatureModel`

`[Class]` `ValueSignatureModel`

`[Class]` `ClassProperty`

`[Class]` `ClassMethod`

`[Class]` `ClassSignatureModel`

`[Class]` `Module`

`[Class]` `ValueExport`

`[Class]` `TypeExport`

`[Class]` `DrillableNamespaceEntrypoint`

`[Class]` `SimpleEntrypoint`

`[Class]` `PackageMetadata`

`[Class]` `Package`

Types

`[I]` `Module`

`[I]` `ValueExport`