@git-stunts/trailer-codec

Robust, Async-First Metadata Encoding for Git Commits.

@git-stunts/trailer-codec is a professional-grade encoder/decoder for structured metadata (trailers) within Git commit messages. It follows the standard Git trailer convention (RFC 822 / Email headers) while providing industrial safety features and a type-safe domain model.

📦 Key Features

• Async-First API: Modernized for v1.0, support for non-blocking encoding/decoding.
• DoS Protection: Built-in 5MB message size limit and ReDoS-hardened regex.
• Structured Domain: Formalized Entities and Value Objects (GitCommitMessage, GitTrailer).
• Zod Validation: Schema-driven validation with diagnostic error objects.
• Pure Domain Logic: Zero I/O, zero subprocesses. Safe for any runtime (Node, Bun, Deno, Web).
• Case Normalization: Automatic normalization of trailer keys for consistent querying.

🚀 Quick Start

Basic Encoding

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

const codec = createDefaultTrailerCodec();

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

Basic Decoding

const payload = await codec.decode(message);

console.log(payload.title);    // "feat: add user authentication"
console.log(payload.trailers); // { "signed-off-by": "James Ross", ... }

📖 Documentation

• Standard Guide - Common patterns and advanced configuration.
• API Reference - Exhaustive export catalog.
• Security Model - Details on DoS and ReDoS protection.
• Integration Recipes - How to use with git log and CI pipelines.

🛠️ Validation Rules

| Rule | Constraint | Thrown Error | |------|------------|--------------| | Message Size | ≤ 5MB | TrailerTooLargeError | | Trailer Key | Alphanumeric, hyphens, underscores | TrailerInvalidError | | Trailer Value | No line breaks, non-empty | TrailerValueInvalidError | | Structure | Blank line must separate body from trailers | TrailerNoSeparatorError |

📄 License

Apache-2.0