Public JavaScript API

Ravel 0.1 favors small, function-oriented packages. The exports described here are public contracts; internal object properties not described here may change within the 0.1 line. Each library package ships a handwritten index.d.ts file alongside its JavaScript entry point.

@pieceful/ravel-map

Use this package at adapter, editor, and host boundaries.

  • validateRavelMap(map, { uri? }) returns diagnostics without throwing.
  • assertRavelMap(map, { uri? }) returns a valid map or throws RavelMapValidationError, whose diagnostics property is portable data.
  • RAVEL_MAP_VERSION, RAVEL_MAP_SCHEMA_ID, and RAVEL_MAP_SCHEMA identify the version-1 interchange contract.
  • @pieceful/ravel-map/schema is the JSON Schema module.

@pieceful/ravel-markdown

  • markdownToMap(text, { uri?, document?, mode? }) converts the documented Markdown fenced profile to { map, diagnostics }. mode is "opt-in" or "primary".

@pieceful/ravel-core

  • parseChunkId and formatChunkId convert canonical chunk identities.
  • parseChunk parses an individual chunk body into portable syntax data.
  • combineMaps(maps) constructs the pre-transform graph.
  • transformGraph(graph, { transforms? }) evaluates that graph and returns the program, deliverables, diagnostics, dependencies, and trace.
  • createDeliverableProvenanceMap(deliverable) and createBuildProvenanceMap(program) construct version-1 sidecar and aggregate generated-output maps.
  • sourceAtGeneratedOffset(map, offset) and generatedRangesForSource(map, uri, offset) provide forward and reverse provenance lookup. Exact results include a corresponding offset; coarse results retain the best attributable range without claiming character identity.
  • generatedRangesForSourceRange(map, uri, range) maps a half-open source range, while explainGeneratedOffset(program, deliverable, offset) adds the definition, references, and dependency path.
  • provenanceMapVersion identifies the generated provenance contract.

The @pieceful/ravel-core/directives entry point exposes constructors for the portable directive IR. Custom transforms are functions that receive a string value and return a string; a failed or non-string result becomes a diagnostic.

@pieceful/ravel-host-node

This Node-only package performs scoped filesystem input and artifact work.

  • loadBuildInput and loadTomlBuild load direct files or version-1 TOML runs.
  • planDeliverables, writeBuildArtifacts, and createBuildManifest support managed artifact production. A managed build writes a .ravelmap sidecar for every deliverable and an aggregate .ravelmap bundle.
  • cleanManagedArtifacts, refreshStaleArtifacts, planOutputBackup, and createOutputBackup implement the safe managed-output lifecycle.

Expected input/configuration failures throw RavelInputError with portable diagnostics. Filesystem failures remain ordinary host errors.

@pieceful/ravel-host-browser

This portable, in-memory host is the boundary used by the live playground.

  • renderMarkdownDocument(source, { uri?, document?, mode?, transforms? }) runs the Markdown adapter, Ravel Map validation, graph transformation, and deliverable provenance construction as one non-throwing operation.
  • The result contains { map, program, deliverables, diagnostics, ok }. Each deliverable includes its version-1 provenanceMap.
  • The host has no filesystem, process, network, loading, or artifact-writing capability. Callers own the source string and any copy/paste interface.

@pieceful/ravel

This package is the installed ravel executable. Its programmatic import is side-effect free for package tooling, but it intentionally exposes no parallel JavaScript command API in 0.1; use the CLI contract instead.