npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@mmmnt/schema

v0.14.0

Published

Schema registry with four-phase lifecycle governance and consumption manifest tracking

Readme

@mmmnt/schema

Schema registry with four-phase field lifecycle governance and consumption manifest tracking.

License: FSL-1.1-Apache-2.0 npm version

Overview

@mmmnt/schema provides schema governance for event-driven systems built with the Moment toolchain. It tracks every field of every registered event schema through a structured four-phase lifecycle -- active, deprecated, end-of-life, and removed -- so that schema changes are announced, planned, and enforced rather than breaking consumers without notice.

The schema registry is an event-sourced aggregate. Registered schema versions are immutable, pre-GA versions (major version below 1) may only add fields, a deprecation must give a reason and replacement guidance, and a field can only reach end-of-life or be removed once it has no active consumers. Every command returns the domain event it applied, and apply() replays recorded events with the same invariants enforced, so a corrupted event stream is refused.

The consumption manifest records which projections consume which event fields and answers the zero-consumer question the registry needs before end-of-life and removal. The Codex rule evaluator is an anti-corruption layer that translates an externally fetched Codex rule pack into schema constraints; its violations are advisory and never block a schema operation, and with no rule pack configured it returns empty results.

Installation

Requires Node.js 22 or newer.

npm install @mmmnt/schema

Or with other package managers:

pnpm add @mmmnt/schema
yarn add @mmmnt/schema

Quick Start

import { SchemaRegistry } from '@mmmnt/schema';

const registry = new SchemaRegistry();

registry.registerEventSchema({
  eventType: 'BookingScheduled',
  version: '1.0.0',
  fieldDefinitions: [
    { fieldName: 'customerId', fieldType: 'UUID', required: true },
    { fieldName: 'vetName', fieldType: 'string', required: false },
  ],
  registeredBy: 'scheduling',
});

registry.deprecateField({
  eventType: 'BookingScheduled',
  fieldName: 'vetName',
  deprecatedSince: '1.0.0',
  reason: 'vets are referenced by id',
  replacement: 'vetId',
});

console.log(registry.getFieldPhase('BookingScheduled', 'vetName')); // 'deprecated'

Key Features

  • Four-phase field lifecycle -- each field moves active → deprecated → end-of-life → removed, and only one step at a time (SR-04).
  • Immutable, versioned schemas -- a schema is registered once per event type and version (SR-01); pre-GA versions are additive-only (SR-05).
  • Guarded deprecation and removal -- deprecation requires a reason and replacement guidance (SR-03); end-of-life and removal require zero active consumers (SR-02).
  • Consumption manifest tracking -- records which projections consume which event fields, validated against the registry, with a later declaration for the same projection superseding the earlier one.
  • Event-sourced state -- the registry and consumption manifest emit and replay SchemaRegistryEvent and ConsumptionManifestEvent, with record shapes (SchemaRegistryRecord, ConsumptionManifestRecord) for .domain/ JSONL logs.
  • Codex rule evaluation -- evaluates naming-convention and field-sensitivity-classification rules from a fetched rule pack; the pack is fetched lazily once per session and cached.
  • Schema evolution validation -- the validateOnSchemaEvolution policy replays registry events and evaluates every registered schema against the rule pack.
  • Payload JSON Schemas -- emitPayloadSchemas(ir) writes one closed JSON Schema (draft 2020-12) per event payload from a model's IR (ADR-049); moment schema emit writes them to files.

Schema Lifecycle

| Phase | Description | |-------|-------------| | active | The field is current. Every field of a newly registered schema starts here. | | deprecated | The field is scheduled for removal. Deprecation records a reason, replacement guidance, and an optional removal target. | | end-of-life | Confirmed only when the field has no active consumers. | | removed | Removed only from end-of-life, with no active consumers and a recorded rationale. |

API Reference

Registry

| Export | Description | |--------|-------------| | SchemaRegistry | Event-sourced catalog of event schemas and per-field lifecycle. Commands: registerEventSchema(RegisterEventSchemaInput), deprecateField(DeprecateFieldInput), confirmEndOfLife(ConfirmEndOfLifeInput), removeField(RemoveFieldInput). Queries: getFieldPhase, hasSchema, getRegisteredEventTypes. Replay with apply(). |

Governance

| Export | Description | |--------|-------------| | ConsumptionManifest | Tracks which projections consume which event fields. declareConsumption(DeclareConsumptionInput, registry) rejects unregistered event types (CM-01). Queries: hasZeroConsumers, getConsumers, getDeclaration. | | CodexRuleEvaluator | Evaluates a schema (SchemaEvaluationInput: event type, version, field names) against a Codex rule pack fetched through an optional RulePackFetcher. Configured with CodexRuleEvaluatorConfig (strategy, fetcher). evaluate() returns a RuleEvaluationResult. |

Payload schemas

| Export | Description | |--------|-------------| | emitPayloadSchemas(ir) | One JSON Schema per declared event, by name, and diagnostics (an undeclared type is a diagnostic, never an open schema). Every object is closed (additionalProperties: false); value objects are in $defs. An optional field is left out of required; a code set is enum; a tagged union is oneOf, one closed branch per variant with kind as const; an exclusive group is oneOf of required; a map types additionalProperties (x-key names the key); [pattern] is pattern; [encrypted] is x-encrypted: true with the {dataKeyId, ciphertext} envelope; UUID, DateTime and Date carry format. | | UNION_TAG | 'kind', the discriminator property of every tagged union. |

Policies

| Export | Description | |--------|-------------| | validateOnSchemaEvolution | Replays SchemaRegistryEvents and evaluates each registered schema with a CodexRuleEvaluator. Returns SchemaEvolutionPolicyResult with per-schema diagnostics and the total violation count. |

Key Types

| Type | Description | |------|-------------| | FieldPhase | 'active' \| 'deprecated' \| 'end-of-life' \| 'removed'. | | FieldDefinition | A field within a schema: fieldName, fieldType, required. | | EventSchemaRegistered | Event emitted when a schema version is registered. | | EventFieldDeprecated | Event emitted when a field is deprecated. | | EventFieldEndOfLife | Event emitted when a field's end-of-life is confirmed. | | EventFieldRemoved | Event emitted when a field is removed. | | SchemaRegistryEvent | Union of all schema registry events. | | ConsumptionEntry | A projection's declaration: projection id and name, product, and consumed events with their fields. | | CodexRule | A rule in a pack: ruleId, ruleType, parameters, severity (error or warning). | | CodexRulePack | A versioned collection of rules with framework and effective date. | | LazyFetchStrategy | How and where to fetch the rule pack: mode (lazy or signal) and optional cdnEndpoint. | | SchemaConstraintViolation | A violation with constraint type, rule id, target, description, and severity. | | RuleEvaluationResult | Pack version, constraints evaluated, violations, and passedAll. | | SchemaEvolutionDiagnostic | The evaluation result for one registered schema version. |

Examples

Walking a Field Through Its Lifecycle

import { SchemaRegistry, ConsumptionManifest } from '@mmmnt/schema';

const registry = new SchemaRegistry();
const manifest = new ConsumptionManifest();

registry.registerEventSchema({
  eventType: 'BookingCompleted',
  version: '1.0.0',
  fieldDefinitions: [
    { fieldName: 'customerId', fieldType: 'UUID', required: true },
    { fieldName: 'cost', fieldType: 'Money', required: true },
  ],
  registeredBy: 'ticketing',
});

manifest.declareConsumption(
  {
    projectionId: 'billing-ledger',
    projectionName: 'BillingLedger',
    product: 'billing-service',
    consumedEvents: [{ eventType: 'BookingCompleted', fields: ['customerId', 'cost'] }],
  },
  registry,
);

registry.deprecateField({
  eventType: 'BookingCompleted',
  fieldName: 'cost',
  deprecatedSince: '1.0.0',
  reason: 'split into fee and tax',
  replacement: 'fee',
});

// SR-02: end-of-life is refused while any projection still consumes the field.
const consumers = manifest.getConsumers('BookingCompleted', 'cost');
console.log(consumers.map((c) => c.projectionName)); // ['BillingLedger']

registry.confirmEndOfLife({
  eventType: 'BookingCompleted',
  fieldName: 'cost',
  confirmedBy: 'ticketing',
  hasActiveConsumers: !manifest.hasZeroConsumers('BookingCompleted', 'cost'),
}); // throws: SR-02 ... active consumers exist

Evaluating Governance Rules

import { CodexRuleEvaluator, SchemaRegistry, validateOnSchemaEvolution } from '@mmmnt/schema';
import type { CodexRulePack, SchemaRegistryEvent } from '@mmmnt/schema';

const evaluator = new CodexRuleEvaluator({
  strategy: { mode: 'lazy', cdnEndpoint: 'https://rules.example.com/pack.json' },
  fetcher: {
    fetch: async (endpoint) => (await (await fetch(endpoint)).json()) as CodexRulePack,
  },
});

// Every registry command returns the event it applied; a stored log replays the same way.
const events: SchemaRegistryEvent[] = [
  new SchemaRegistry().registerEventSchema({
    eventType: 'CustomerRegistered',
    version: '1.0.0',
    fieldDefinitions: [{ fieldName: 'customer_id', fieldType: 'UUID', required: true }],
    registeredBy: 'ticketing',
  }),
];
const result = await validateOnSchemaEvolution(events, evaluator);

console.log(`${result.evaluatedSchemas} schema(s), ${result.totalViolations} violation(s)`);
for (const { eventType, version, evaluationResult } of result.diagnostics) {
  for (const v of evaluationResult.violations) {
    console.log(`[${v.severity}] ${eventType}@${version} ${v.ruleId}: ${v.description}`);
  }
}

Without a cdnEndpoint and fetcher, or when the fetch fails, evaluation returns empty results rather than failing.

Integration

@mmmnt/schema declares @mmmnt/core as its dependency and is used by the CLI:

@mmmnt/core --> @mmmnt/schema
                     |
                     +-- @mmmnt/cli  (exposed via `moment schema status`)

Contributing

This package is part of the mmmnt monorepo. See CONTRIBUTING.md for development setup and contribution guidelines.

git clone https://github.com/mmmnt/mmmnt.git
cd mmmnt
pnpm install
pnpm turbo build --filter=@mmmnt/schema
pnpm --filter @mmmnt/schema test

License

FSL-1.1-Apache-2.0