@refinest/config

Inert JSON and YAML declaration sources for refinest: read an admin's resources, fields, and menus out of a config file instead of writing them in TypeScript.

The package exists to make that safe. A config file is data, so it may declare only data — never an action, provider, mapper, service, credential, schema, component, or validator. Those are code, and code cannot be smuggled in through a value. What comes out the other side is an inert LayerInput the host may publish, or a list of diagnostics explaining exactly why it refused.

Install

pnpm add @refinest/config @refinest/core

Usage

Parsing is a pure function over text, bounded by a policy you own:

import { parseYamlLayer } from '@refinest/config';

const policy = {
  allowedKinds: ['resource', 'field'],
  allowedNamespaces: ['app'],
  allowedTransformOps: ['merge', 'disable'],
  maxTransformScope: 'namespace',
  allowedCapabilities: { field: ['string', 'number', 'ref'] },
  limits: {
    maxBytes: 64_000,
    maxDeclarations: 500,
    maxDepth: 12,
    maxStringLength: 4_000,
    maxDiagnostics: 20,
  },
};

const result = parseYamlLayer(text, policy);
if (result.ok) publish(result.value);
else console.error(result.diagnostics);

To load config at runtime rather than at build time, wrap the same adapter in a core runtime source — publication, cancellation, epochs, and snapshot commits stay with core's LayerRuntime:

import { createConfigRuntimeSource, parseResultAdapter } from '@refinest/config';

const source = createConfigRuntimeSource(
  'remote-config',
  async () => parseJsonLayer(await fetchText(), policy),
  parseResultAdapter,
  policy,
);

Main exports

• parseJsonLayer / parseYamlLayer — text to a ParseResult: either an inert layer or diagnostics. Both reject prototype-polluting keys, over-limit documents, and any value in a forbidden category.
• SourcePolicy / SourceLimits — the host-owned allowlist and resource bounds. Every parse is scoped by one; there is no permissive default.
• adaptRawConfig / parseResultAdapter / SourceAdapter — the seam for your own format. Write an adapter from your raw shape to declarations and the same policy boundary applies to it, including a frozen context whose only side effect is diagnose().
• createConfigRuntimeSource — presents an adapter as a RuntimeSource for core's layer runtime.

License

MIT