@hyperfrontend/features/generators

generators

Pure code generators that turn a resolved feature config and parsed contract into staged output files.

API

Export	Purpose
`generateShell`	Stages the self-contained shell package (entry, `package.json`, README, metadata); composes only the feature's declared display modes and narrows the generated types to them.
`generateMetadata`	Stages the shell's `metadata.json` with a version-stamped, embedded contract and the declared display modes.
`generateFeatureModule`	Stages the feature integration module (`src/hyperfrontend.feature.ts`); regenerates it only while pristine and never clobbers author edits.
`generateContractTypes`	Bridges a `.json` contract to a sibling `.d.ts` of literal-type unions.

Usage

import { createTree } from '@hyperfrontend/project-scope/vfs'
import { generateShell } from '@hyperfrontend/features/generators'

const tree = createTree('/tmp/clock-shell')
generateShell({ name: 'clock', version: '1.0.0', contract: './clock.contract.json', url: '/clock' }, contract, tree)

API Reference

ƒ Functions

§function

generateContractTypes(config: ResolvedFeatureConfig, contract: FeatureContract, tree: Tree): ContractTypesOutcome

Stages a .d.ts of literal-type declarations beside a JSON contract.
Only .json contracts need this bridge; .ts as const contracts derive types via typeof and are skipped (no file is staged). The declaration file is machine-owned: a stale one is regenerated, and an identical one is left unstaged so re-runs stay no-ops. Pure: stages only into tree.

Parameters

Name	Type	Description
§config	`ResolvedFeatureConfig`	The resolved feature config naming the feature and contract path.
§contract	`FeatureContract`	The validated contract whose literals are preserved.
§tree	`Tree`	The VFS tree the declaration file is staged into.

Returns

ContractTypesOutcome

Whether the declaration was staged as created, staged as updated, kept as-is, or skipped for a non-JSON contract.

Example

Bridging a JSON contract to literal types

const outcome = generateContractTypes({ name: 'clock', version: '1.0.0', contract: './clock.contract.json', url: '/clock' }, contract, tree)

View source →

§function

generateFeatureModule(config: ResolvedFeatureConfig, contract: FeatureContract, tree: Tree, previousConfig?: ResolvedFeatureConfig): FeatureModuleOutcome

Stages the feature integration module into the consumer app.
Emits src/hyperfrontend.feature.ts with one feature.on stub per accepted action and a commented feature.send example per emitted action. The module is machine-owned only while pristine: a missing module is created, a module still byte-identical to its previous machine render (reconstructed from previousConfig and the current contract) is regenerated, and a module the author has edited is always kept untouched. The CLI owns inserting the marker-guarded import into the entry file.

Parameters

Name	Type	Description
§config	`ResolvedFeatureConfig`	The resolved feature config.
§contract	`FeatureContract`	The validated feature contract driving the scaffolded stubs.
§tree	`Tree`	The VFS tree the integration module is staged into.
§previousConfig?	`ResolvedFeatureConfig`	Prior resolved config used to recognize a pristine module; omit to never overwrite an existing module.

Returns

FeatureModuleOutcome

Whether the module was staged as created, staged as updated, or kept as-is.

Example

Scaffolding the integration module for the clock feature

const outcome = generateFeatureModule({ name: 'clock', version: '1.0.0', contract: './clock.contract.json', url: '/clock' }, contract, tree)

View source →

§function

generateMetadata(config: ResolvedFeatureConfig, contract: FeatureContract, tree: Tree): void

Stages the shell's metadata.json describing the feature and its contract.
Stamps a canonical version string via @hyperfrontend/versioning and embeds the contract, the baked security protocol, any declared browser permissions, and the version of the SDK that ran the build, so humans and the registry can inspect the feature without unpacking the bundle. The staged file matches FeatureDescriptor.

Parameters

Name	Type	Description
§config	`ResolvedFeatureConfig`	The resolved feature config supplying name, version, URL, and protocol.
§contract	`FeatureContract`	The validated contract embedded for inspection.
§tree	`Tree`	The VFS tree the metadata file is staged into.

Example

Staging metadata for the clock feature

generateMetadata({ name: 'clock', version: '1.0.0', contract: './clock.contract.json', url: '/clock', protocol: 'v2' }, contract, tree)

View source →

§function

generateShell(config: ResolvedFeatureConfig, contract: FeatureContract, tree: Tree): void

Stages the complete shell package into the supplied VFS tree.
Emits the entry source (with contract-projected types), source-level package.json, README.md, and (via generateMetadata) metadata.json. Pure: stages only into tree — the CLI owns temp-dir creation, bundling, and commit.

Parameters

Name	Type	Description
§config	`ResolvedFeatureConfig`	The resolved feature config.
§contract	`FeatureContract`	The validated feature contract, inlined into the shell.
§tree	`Tree`	The VFS tree the shell files are staged into.

Example

Staging a shell for the clock feature

generateShell({ name: 'clock', version: '1.0.0', contract: './clock.contract.json', url: '/clock', protocol: 'v2' }, contract, tree)

View source →