@burojs/core

The declarative heart of buro: resource/app definitions, the field builder, the registry, and the action dispatcher.

Zero runtime dependencies, and it imports React nowhere — this package is plain data and pure functions, so it can be consumed from a server, a test, or any UI layer.

Install

pnpm add @burojs/core @burojs/field-types

Usage

A complete CRUD resource — list, show, edit, create, sidebar placement, labels, search and column selection — is a single declaration:

import { defineApp, defineResource } from '@burojs/core';
import { f } from '@burojs/field-types';

const company = defineResource(
  'company',
  {
    texts: { label: 'Company', labelPlural: 'Companies' },
    displayField: 'name',
    fields: {
      id: f.number({ system: true, texts: 'ID' }),
      name: f.string({ texts: 'Name' }),
      created_at: f.dateTime({ system: true, texts: 'Created' }),
    },
    views: { list: { columns: ['id', 'name', 'created_at'], search: { fields: ['name'] } } },
  },
);

const app = defineApp({ name: 'admin' });
app.use(company);

texts.label names one record and texts.labelPlural the collection — the sidebar, the list page, a related list. Both are plain defaults; translations live in the i18n bundle under resources.<name>.label and resources.<name>.labelPlural. A label missing from the active locale comes from the fallback locale, then from the default in code, then from the humanized resource name; a resource that declares no labelPlural titles its collection with the translated label. Text that shows a number is the app's own, by convention under the count family resources.<name>.count_one | _few | _many | _other, read with t(key, { count }). Every other element's bundle key — fields, options, enums, checks, navigation — is in one table in docs/i18n-guide.md.

Point a resource at a non-default data provider by declaring it — no wiring:

defineResource('schedules', { meta: { dataProviderName: 'temporal' } /* … */ });

Portable declaration kernel

For framework-neutral configuration, register a small open kind and compile portable declarations into an immutable snapshot. Relative declaration references are installed in the layer namespace; use namespace:id when the reference is intentionally cross-namespace.

import {
  TRUSTED_CODE,
  compileApplicationDefinition,
  createKindRegistry,
  defineTrustedBundle,
} from '@burojs/core';

interface ResourceInput {
  readonly label: string;
}

function parseResource(value: unknown): ResourceInput {
  if (
    value === null
    || typeof value !== 'object'
    || Array.isArray(value)
    || Object.keys(value).length !== 1
    || !Object.prototype.hasOwnProperty.call(value, 'label')
    || !('label' in value)
    || typeof value.label !== 'string'
  ) {
    throw new TypeError('A resource must contain exactly one string label.');
  }
  return { label: value.label };
}

const resourceKind = {
  kind: 'resource',
  schemaVersion: 1,
  schema: { parse: parseResource },
  compile: (value: ResourceInput) => ({ label: value.label }),
};

const catalog = defineTrustedBundle({
  defaultNamespace: 'catalog',
  declarations: [{ kind: 'resource', ref: 'products', schemaVersion: 1, value: { label: 'Products' } }],
  implementations: [],
  handle: { source: 'catalog' },
});

const result = compileApplicationDefinition({
  compilerVersion: 'my-app-v1',
  kinds: createKindRegistry([resourceKind]),
  layers: [{
    input: {
      id: 'catalog',
      priority: 0,
      defaultNamespace: catalog.defaultNamespace,
      declarations: catalog.declarations,
    },
    trust: TRUSTED_CODE,
  }],
});

if (result.ok) {
  result.snapshot.getProjection({ kind: 'resource', ref: 'catalog:products' });
}

Every layer reaches the compiler with a trust value. TRUSTED_CODE marks a layer your own code builds; a layer parsed from JSON or YAML carries the LayerGrants of the policy it was parsed under (see @burojs/config), and the compiler checks against them the kinds, namespaces and transform operations the layer uses, the paths its transforms write, the declarations they target, the resources, queries and mutations it references, and the backends it binds. Trusted-attachment capabilities and the forbidden keys (action, component, validator, …) are not grants: only @burojs/config's parser checks them. A layer without a trust value is invalid-input.

defineTrustedBundle() keeps trusted implementation definitions alongside declarations for the application runtime, but snapshot.manifest is deliberately portable: it contains no functions, components, services, credentials, or implementation objects. It can therefore be JSON-serialized safely after the application applies its own XSS-safe transport.

The runtime declaration exports are normalizeEntityRef, formatEntityRef, sameEntityRef, EntityRefError, defineTrustedBundle, isTrustedDeclarationBundle, TRUSTED_CODE, normalizeLayerGrants, createKindRegistry, compileApplicationDefinition, DEFAULT_COMPILER_LIMITS, createApplicationSnapshot, and explainSnapshot.

Main exports

• defineApp / defineResource / extendResource — the application declaration surface. A resource's fields is a plain object built with f from @burojs/field-types (or an extendFieldBuilder result); its record screens (views.show / edit / create, with header, body, with and types) are planned and checked from P1a and rendered from P1b.
• defineGroup / defineSection / defineCustomPage — navigation structure and non-resource pages; see the navigation guide for groups, layouts and URLs.
• defineEnum — enum registries. Record variants are types on the resource, and a multi-step create is a steps node in views.create.body.
• createFieldBuilder / createFieldRegistry — the field-builder primitives the above compose.
• createDispatcher — turns an action invocation into an ActionResult (notify / refetch / redirect / clearSelection …) that a UI layer applies.
• evaluateVisible — the shared predicate evaluator behind field, column and nav visibility.
• Data-access ports — ActionDataAccess and CountCapable (getCount?, the on-demand row count), declared here precisely because this package has no dependencies.

License

MIT