API/devkit

@functional-examples/devkit

Plugin development kit for functional-examples

npm install @functional-examples/devkit

@functional-examples/devkit

Plugin development kit for functional-examples — shared types and utilities.

Installation

npm install @functional-examples/devkit

Overview

The devkit provides the foundational types and utility modules used by functional-examples and its plugins.

Usage

Types (root)

import type {
  Config,
  Example,
  Extractor,
  Plugin,
} from '@functional-examples/devkit';

Core type definitions: Plugin, Extractor, ExtractorResult, Config, Example, ExampleFile, and more.

Utilities (root)

import {
  createMatcher,
  glob,
  isMatch,
  JsonParseError,
  parseJson,
  parseYaml,
  tryParseJson,
  tryParseYaml,
  YamlParseError,
} from '@functional-examples/devkit';

Includes JSON parsing (parseJson, tryParseJson, JsonParseError), YAML parsing (parseYaml, tryParseYaml, YamlParseError), and glob helpers (glob, isMatch, createMatcher) from the root import.

Peer Dependencies

The utility helpers rely on optional peer dependencies:

Utility area	Optional peers
Glob helpers	`tinyglobby`, `picomatch`
YAML parser	`yaml`
JSON parser	`jsonc-parser` and/or `json5` for extended formats

License

MIT

API EXPORTS

Functions

createMatcherfunction

Create a reusable matcher function from one or more glob patterns. Prefer this over repeated isMatch calls when matching many paths against the same pattern—the compiled matcher is significantly faster for repeated use. Requires the `picomatch` peer dependency to be installed.

globfunction

Find files matching glob patterns. Thin wrapper around tinyglobby that normalizes input and provides a consistent interface across the monorepo. Requires the `tinyglobby` peer dependency to be installed.

isMatchfunction

Test whether a path matches one or more glob patterns. Requires the `picomatch` peer dependency to be installed.

parseJsonfunction

Parses a JSON string with progressive fallbacks: 1. Standard JSON.parse 2. jsonc-parser (handles comments and trailing commas) 3. json5 (handles extended JSON5 syntax) If all parsers fail, throws a JsonParseError with a formatted code frame showing the error location.

parseYamlfunction

Parse a YAML string into a typed value. Requires the `yaml` peer dependency to be installed.

tryParseJsonfunction

Wraps parseJson in a try/catch, returning a discriminated union indicating success or failure.

tryParseYamlfunction

Try to parse a YAML string, returning a discriminated union result instead of throwing. Requires the `yaml` peer dependency to be installed.

Classes

ExampleFileclass

A file within an example, with optional processed content.

JsonParseErrorclass

Error thrown when JSON parsing fails across all available parsers.

ScannedExampleclass

An example after processing by the scanner. Includes computed fields like displayPath that are added during scanning.

YamlParseErrorclass

Error thrown when YAML parsing fails. Includes optional position information for diagnostics.

Interfaces

BaseMetadatainterface

Base metadata that all examples should have. Used for type constraints when users want stricter typing.

Configinterface

ConfigValidationErrorinterface

Error from config validation.

Exampleinterface

A discovered example with metadata and files. This is the base type returned by extractors. Metadata is typed via `ExampleMetadata` by default, which can be augmented by running `functional-examples generate`. You can also pass an explicit generic parameter for custom typing.

ExampleMetadataRegistryinterface

Augmentable registry for example metadata typing. Run `functional-examples generate` to create a declaration file that augments this interface, providing type-safe metadata for your examples.

Extractorinterface

Candidate-based extractor interface. Called with pre-filtered candidates (files and/or directories). Extractor decides which candidates it can handle.

ExtractorConfiginterface

Reference to an extractor package (for config files)

ExtractorErrorinterface

Error encountered during extraction

ExtractorOptionsinterface

Options passed to extractor during extraction

ExtractorResultinterface

Result from a candidate-based extractor

FileContentsParserinterface

Parser that processes file contents in a pipeline. Receives accumulated context, transforms it, returns updated context.

FileParseContextinterface

Context passed through the FileContentsParser pipeline. Each parser receives this, transforms it, and returns an updated version.

GenerateConfiginterface

Configuration for the generate command output.

GlobOptionsinterface

Options for the glob function.

JSONSchemaObjectinterface

JSON Schema object for metadata validation. Subset of JSON Schema spec used for config files.

ParsedRegioninterface

Parsed code region from #region markers.

PathMappinginterface

Path-to-extractor mapping for conflict resolution.

Plugininterface

Plugin containing optional extractors, parsers, schemas, and validators. Auto-registers for declared file extensions.

PluginRegistryInterfaceinterface

Plugin registry interface for accessing validators/schemas. Full implementation is in plugins/registry.ts.

PluginSchemaEntryinterface

Schema entry from a plugin with plugin name context.

PluginSchemasinterface

Schema definitions for a plugin (JSON Schema format). Used for IDE autocomplete and documentation generation.

PluginValidatorEntryinterface

Wrapper for a plugin's validator function with plugin name context.

PluginValidatorsinterface

Validator functions for a plugin. Allows plugins to use any validation library (Zod, TypeBox, etc.)

RegionConfiginterface

Configuration for region marker parsing.

ResolvedConfiginterface

Resolved configuration with actual extractor instances. This is the runtime-ready configuration after all plugins are loaded.

ScanConfiginterface

Scan configuration options.

ValidationErrorinterface

A single validation error.

ValidationResultinterface

Result of a validation operation.

Types

ConfigWithRoottype

Full configuration (alias for BaseConfig)

ExampleMetadatatype

Resolved example metadata type. If `ExampleMetadataRegistry` has been augmented with a `metadata` property, this resolves to that type. Otherwise, falls back to `Record<string, unknown>`. This allows the `generate` command to provide project-specific types that automatically apply to all `Example` types without explicit generic parameters.

ExtractorConfigOrFunctiontype

An extractor can be a reference (to load) or an instance

ExtractorFactorytype

Factory function to create an extractor with options

ExtractorReferencetype

Extractor can be specified as string (package name) or full config

PluginCommandstype

Plugin commands can be a static array or a function that receives the resolved config and returns commands (sync or async). Uses `CLI<any, any, any, any>` because each command defines its own args/handler shape — the plugin system doesn't need to know specifics.

PluginReferencetype

A reference to a plugin by package name, optionally with options. In JSON configs, plugins can be specified as: - A string: `"@functional-examples/yaml-manifest"` - A tuple: `["@functional-examples/javascript", { "regionTag": "#_" }]`

TypeGuardtype