@git-stunts/trailer-codec

A robust encoder/decoder for structured metadata within Git commit messages.

Key Features

• Standard Compliant: Follows the Git "trailer" convention (RFC 822 / Email headers)
• DoS Protection: Built-in 5MB message size limit to prevent attacks
• Structured Domain: Formalized entities and value objects for type safety
• Zod Validation: Schema-driven validation with helpful error messages
• Case Normalization: Trailer keys normalized to lowercase for consistency
• Pure Domain Logic: No I/O, no Git subprocess execution

Design Principles

1. Domain Purity: Core logic independent of infrastructure
2. Type Safety: Value Objects ensure data validity at instantiation
3. Immutability: All entities are immutable
4. Separation of Concerns: Encoding/decoding in dedicated service

Prerequisites

• Node.js: >= 20.0.0

Installation

npm install @git-stunts/trailer-codec

Developer & Testing

• Node.js ≥ 20 matches the engines field in package.json and is required for Vitest/ESM support.
• npm test runs the Vitest suite, npm run lint validates the code with ESLint, and npm run format formats files with Prettier; all scripts target the entire repo root.
• Consult TESTING.md for run modes, test filters, and tips for extending the suite before submitting contributions.

Usage

Basic Encoding/Decoding

import { createDefaultTrailerCodec } from '@git-stunts/trailer-codec';

const codec = createDefaultTrailerCodec();
const message = codec.encode({
  title: 'feat: add user authentication',
  body: 'Implemented OAuth2 flow with JWT tokens.',
  trailers: [
    { key: 'Signed-off-by', value: 'James Ross' },
    { key: 'Reviewed-by', value: 'Alice Smith' },
  ],
});

console.log(message);
// feat: add user authentication
//
// Implemented OAuth2 flow with JWT tokens.
//
// signed-off-by: James Ross
// reviewed-by: Alice Smith

const decoded = codec.decode(message);
console.log(decoded.title);      // "feat: add user authentication"
console.log(decoded.trailers);   // { 'signed-off-by': 'James Ross', 'reviewed-by': 'Alice Smith' }

API Patterns

• Primary entry point: createDefaultTrailerCodec() returns a TrailerCodec wired with a fresh TrailerCodecService; use .encode()/.decode() (or .encodeMessage()/.decodeMessage()) to keep configuration in one place.
• Facade: TrailerCodec keeps configuration near instantiation while still leveraging createMessageHelpers() under the hood (pass your own service when you need control).
• Advanced: createConfiguredCodec() and direct TrailerCodecService usage let you swap schema bundles, parsers, formatters, or helper overrides when you need custom validation or formatting behavior. The standalone helpers encodeMessage()/decodeMessage() remain available as deprecated convenience wrappers.

Breaking Changes

• decodeMessage() now trims trailing newlines in the version v0.2.0+ runtime, so plain string inputs will no longer include a final \n unless you opt into it.
• To preserve the trailing newline you rely on (e.g., when round-tripping commit templates), either instantiate TrailerCodec with bodyFormatOptions: { keepTrailingNewline: true }, call formatBodySegment(body, { keepTrailingNewline: true }) yourself, or pass the same option through createConfiguredCodec.
• See docs/MIGRATION.md#v020 for the full migration checklist and decoding behavior rationale.

Body Formatting & Facade

decodeMessage now trims the decoded body by default, returning the content exactly as stored; no extra newline is appended automatically. If you still need the trailing newline (for example when writing the decoded body back into a commit template), instantiate the helpers or facade with bodyFormatOptions: { keepTrailingNewline: true }:

import TrailerCodec from '@git-stunts/trailer-codec';

const codec = new TrailerCodec({ bodyFormatOptions: { keepTrailingNewline: true } });
const payload = codec.decode('Title\n\nBody\n');
console.log(payload.body); // 'Body\n'

You can also call the exported formatBodySegment(body, { keepTrailingNewline: true }) helper directly when you need the formatting logic elsewhere.

import { formatBodySegment } from '@git-stunts/trailer-codec';

const trimmed = formatBodySegment('Body\n', { keepTrailingNewline: true });
console.log(trimmed); // 'Body\n'

Advanced

Configured Codec Builder

When you need a prewired codec (custom key patterns, parser tweaks, formatter hooks), use createConfiguredCodec({ keyPattern, keyMaxLength, parserOptions }). It builds a schema bundle, parser, and service for you, and returns helpers so you can immediately call decodeMessage/encodeMessage:

import { createConfiguredCodec } from '@git-stunts/trailer-codec';

const { decodeMessage, encodeMessage } = createConfiguredCodec({
  keyPattern: '[A-Za-z._-]+',
  keyMaxLength: 120,
  parserOptions: {},
});

const payload = { title: 'feat: cli docs', trailers: { 'Custom.Key': 'value' } };
const encoded = encodeMessage(payload);
const decoded = decodeMessage(encoded);
console.log(decoded.title); // 'feat: cli docs'

Domain Entities

import { GitCommitMessage } from '@git-stunts/trailer-codec';

const msg = new GitCommitMessage({
  title: 'fix: resolve memory leak',
  body: 'Fixed WeakMap reference cycle.',
  trailers: [
    { key: 'Issue', value: 'GH-123' },
    { key: 'Signed-off-by', value: 'James Ross' }
  ]
});

console.log(msg.toString());

Public API Helpers & Configuration

• formatBodySegment(body, { keepTrailingNewline = false }) mirrors the helper powering decodeMessage, trimming whitespace while optionally preserving the trailing newline when you plan to write the body back into a template.
• createMessageHelpers({ service, bodyFormatOptions }) returns { decodeMessage, encodeMessage } bound to the provided TrailerCodecService; pass bodyFormatOptions to control whether decoded bodies keep their trailing newline.
• TrailerCodec wraps createMessageHelpers() so you can instantiate a codec class with custom service or bodyFormatOptions and still leverage the helper contract via encode()/decode().
• createConfiguredCodec({ keyPattern, keyMaxLength, parserOptions, formatters, bodyFormatOptions }) wires together createGitTrailerSchemaBundle, TrailerParser, TrailerCodecService, and the helper pair, letting you configure key validation, parser heuristics, formatting hooks, and body formatting in a single call.
• TrailerCodecService exposes the schema bundle, parser, trailer factory, formatter hooks, and helper utilities (MessageNormalizer, extractTitle, composeBody); see docs/SERVICE.md for a deeper explanation of how to customize each stage without touching the core service.

✅ Validation Rules

Trailer codec enforces strict validation via the concrete subclasses of TrailerCodecError:

| Rule | Constraint | Thrown Error | |------|------------|--------------| | Message Size | ≤ 5MB | TrailerTooLargeError | | Title | Must be a non-empty string | CommitMessageInvalidError (during entity construction) | | Trailer Key | Alphanumeric, hyphens, underscores only (/^[A-Za-z0-9_-]+$/) and ≤ 100 characters (prevents ReDoS) | TrailerInvalidError | | Trailer Value | Cannot contain carriage returns or line feeds and must not be empty | TrailerValueInvalidError |

Key Normalization: All trailer keys are automatically normalized to lowercase (e.g., Signed-Off-By → signed-off-by).

Blank-Line Guard: Trailers must be separated from the body by a blank line; omitting the separator throws TrailerNoSeparatorError.

Validation Errors

When TrailerCodecService or the exported helpers throw, they surface one of the following classes so you can recover with instanceof checks:

| Error | Trigger | Suggested Fix | | --- | --- | --- | | TrailerTooLargeError | Message exceeds 5MB while MessageNormalizer.guardMessageSize() runs | Split the commit or remove content until the payload fits. | | TrailerNoSeparatorError | Missing blank line before trailers when TrailerParser.split() runs | Insert the required empty line between body and trailers. | | TrailerValueInvalidError | Trailer value includes newline characters or fails the schema value rules | Remove or escape newline characters before encoding. | | TrailerInvalidError | Trailer key/value pair fails the schema validation (GitTrailerSchema) | Adjust the key/value or supply a custom schema bundle via TrailerCodecService. | | CommitMessageInvalidError | GitCommitMessageSchema rejects the full payload (title/body/trailers) | Fix the invalid field or pass a conforming payload; use formatters if needed. |

All of the above inherit from TrailerCodecError (src/domain/errors/TrailerCodecError.js) and expose meta for diagnostics; prefer checking the specific class instead of inspecting code.

🛡️ Security

• No Code Execution: Pure string manipulation, no eval() or dynamic execution
• DoS Protection: Rejects messages > 5MB
• ReDoS Prevention: Max key length limits regex execution time
• No Git Subprocess: Library performs no I/O operations
• Line Injection Guard: Trailer values omit newline characters so no unexpected trailers can be injected

See SECURITY.md for details.

📚 Additional Documentation

• docs/ADVANCED.md — Custom schema injection, validation overrides, and advanced integration patterns.
• docs/PARSER.md — Step-by-step explanation of the backward-walk parser.
• docs/INTEGRATION.md — Git log scripting, streaming decoder, and Git-CMS filtering recipes.
• docs/SERVICE.md — How TrailerCodecService wires schema, parser, and formatter helpers for customization.
• API_REFERENCE.md — Complete catalog of the public exports, their inputs/outputs, and notable knobs.
• TESTING.md — How to run/extend the Vitest, lint, and format scripts plus contributor tips.
• Git hooks: Run npm run setuphooks once per clone to point core.hooksPath at scripts/. The hook now runs just npm run lint and npm run format before each commit.

License

Apache-2.0 Copyright © 2026 James Ross