roarr 2.15.4

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/roarr@2.15.4
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/roarr@2.15.4

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:ba278973835fd0f283c1bfdef0beb92466b252b2fb7e4de915429fdbe7d1ba08","contract":["Roarr formats and dispatches structured log messages containing context, message, sequence, and version","Roarr interpolates sprintf placeholder specifiers into message strings with positional arguments","Roarr accepts a context object as the first argument and attaches it to the log record","Roarr.child creates a child logger that inherits and merges parent context properties","Roarr.child with a transform function modifies log payload before dispatching","Roarr provides severity methods (trace, debug, info, warn, error, fatal) that set numeric logLevel in context","Roarr.getContext returns the current accumulated context object","ROARR.write receives serialized JSON log strings to allow custom transport routing","Roarr throws a TypeError when context is provided and message is not a string"],"goal":"verify pkg:npm/roarr@2.15.4","kind":"HOW","packages":["pkg:npm/roarr@2.15.4"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/roarr@2.15.4"],"schemaVersion":1,"subject":"pkg:npm/roarr@2.15.4","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-roarr",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-roarr",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "roarr": "2.15.4"
      }
    },
    "node_modules/boolean": {
      "version": "3.2.0",
      "resolved": "https://registry.npmjs.org/boolean/-/boolean-3.2.0.tgz",
      "integrity": "sha512-d0II/GO9uf9lfUHH2BQsjxzRJZBdsjgsBiW4BvhWk/3qoKwQFjIDVN19PfX8F2D/r9PCMTtLWjYVCFrpeYUzsw==",
      "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
      "license": "MIT"
    },
    "node_modules/define-data-property": {
      "version": "1.1.4",
      "resolved": "https://registry.npmjs.org/define-data-property/-/define-data-property-1.1.4.tgz",
      "integrity": "sha512-rBMvIzlpA8v6E+SJZoo++HAYqsLrkg7MSfIinMPFhmkorw7X+dOXVJQs+QT69zGkzMyfDnIMN2Wid1+NbL3T+A==",
      "license": "MIT",
      "dependencies": {
        "es-define-property": "^1.0.0",
        "es-errors": "^1.3.0",
        "gopd": "^1.0.1"
      },
      "engines": {
        "node": ">= 0.4"
      },
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/define-properties": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/define-properties/-/define-properties-1.2.1.tgz",
      "integrity": "sha512-8QmQKqEASLd5nx0U1B1okLElbUuuttJ/AnYmRXbbbGDWh6uS208EjD4Xqq/I9wK7u0v6O08XhTWnt5XtEbR6Dg==",
      "license": "MIT",
      "dependencies": {
        "define-data-property": "^1.0.1",
        "has-property-descriptors": "^1.0.0",
        "object-keys": "^1.1.1"
      },
      "engines": {
        "node": ">= 0.4"
      },
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/detect-node": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/detect-node/-/detect-node-2.1.0.tgz",
      "integrity": "sha512-T0NIuQpnTvFDATNuHN5roPwSBG83rFsuO+MXXH9/3N1eFbn4wcPjttvjMLEPWJ0RGUYgQE7cGgS3tNxbqCGM7g==",
      "license": "MIT"
    },
    "node_modules/es-define-property": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz",
      "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/es-errors": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz",
      "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/globalthis": {
      "version": "1.0.4",
      "resolved": "https://registry.npmjs.org/globalthis/-/globalthis-1.0.4.tgz",
      "integrity": "sha512-DpLKbNU4WylpxJykQujfCcwYWiV/Jhm50Goo0wrVILAv5jOr9d+H+UR3PhSCD2rCCEIg0uc+G+muBTwD54JhDQ==",
      "license": "MIT",
      "dependencies": {
        "define-properties": "^1.2.1",
        "gopd": "^1.0.1"
      },
      "engines": {
        "node": ">= 0.4"
      },
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/gopd": {
      "version": "1.2.0",
      "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz",
      "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
      },
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/has-property-descriptors": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/has-property-descriptors/-/has-property-descriptors-1.0.2.tgz",
      "integrity": "sha512-55JNKuIW+vq4Ke1BjOTjM2YctQIvCT7GFzHwmfZPGo5wnrgkid0YQtnAleFSqumZm4az3n2BS+erby5ipJdgrg==",
      "license": "MIT",
      "dependencies": {
        "es-define-property": "^1.0.0"
      },
      "funding": {
        "url": "https://github.com/sponsors/ljharb"
      }
    },
    "node_modules/json-stringify-safe": {
      "version": "5.0.1",
      "resolved": "https://registry.npmjs.org/json-stringify-safe/-/json-stringify-safe-5.0.1.tgz",
      "integrity": "sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA==",
      "license": "ISC"
    },
    "node_modules/object-keys": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/object-keys/-/object-keys-1.1.1.tgz",
      "integrity": "sha512-NuAESUOUMrlIXOfHKzD6bpPu3tYt3xvjNdRIQ+FeT0lNb4K8WR70CaDxhuNguS2XG+GjkyMwOzsN5ZktImfhLA==",
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
      }
    },
    "node_modules/roarr": {
      "version": "2.15.4",
      "resolved": "https://registry.npmjs.org/roarr/-/roarr-2.15.4.tgz",
      "integrity": "sha512-CHhPh+UNHD2GTXNYhPWLnU8ONHdI+5DI+4EYIAOaiD63rHeYlZvyh8P+in5999TTSFgUYuKUAjzRI4mdh/p+2A==",
      "license": "BSD-3-Clause",
      "dependencies": {
        "boolean": "^3.0.1",
        "detect-node": "^2.0.4",
        "globalthis": "^1.0.1",
        "json-stringify-safe": "^5.0.1",
        "semver-compare": "^1.0.0",
        "sprintf-js": "^1.1.2"
      },
      "engines": {
        "node": ">=8.0"
      }
    },
    "node_modules/semver-compare": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/semver-compare/-/semver-compare-1.0.0.tgz",
      "integrity": "sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow==",
      "license": "MIT"
    },
    "node_modules/sprintf-js": {
      "version": "1.1.3",
      "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.1.3.tgz",
      "integrity": "sha512-Oo+0REFV59/rz3gfJNKQiBlwfHaSESl1pcGyABQsnnIfWOFt6JNj5gCog2U6MLZ//IGYD+nA8nI+mTShREReaA==",
      "license": "BSD-3-Clause"
    }
  }
}

{
  "name": "sample-roarr",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "roarr": "2.15.4"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/roarr@2.15.4",
  "kind": "HOW",
  "packages": [
    "pkg:npm/roarr@2.15.4"
  ]
}

if (process.env.ROARR_LOG === undefined) {
  process.env.ROARR_LOG = 'true';
}

const roarrPkg = await import('roarr');
const Roarr = roarrPkg.default?.default || roarrPkg.default;
const ROARR = roarrPkg.default?.ROARR || roarrPkg.ROARR;

export const logLevels = {
  trace: 10,
  debug: 20,
  info: 30,
  warn: 40,
  error: 50,
  fatal: 60,
};

/**
 * Creates a scoped logger with preset context metadata.
 * @param {object} initialContext - Initial context properties.
 * @returns {Function} Scoped Roarr logger instance.
 */
export function createScopedLogger(initialContext = {}) {
  return Roarr.child(initialContext);
}

/**
 * Creates a memory buffer writer that captures serialized Roarr logs.
 * @returns {{ write: Function, getMessages: Function, clear: Function }}
 */
export function createBufferWriter() {
  const messages = [];
  return {
    write(rawMessage) {
      try {
        messages.push(JSON.parse(rawMessage));
      } catch {
        messages.push({ raw: rawMessage });
      }
    },
    getMessages() {
      return [...messages];
    },
    clear() {
      messages.length = 0;
    },
  };
}

export { Roarr, ROARR };
export default Roarr;

import assert from 'node:assert/strict';
import {
  Roarr,
  ROARR,
  logLevels,
  createScopedLogger,
  createBufferWriter,
} from '../src/index.mjs';

// Setup buffer capture
const buffer = createBufferWriter();
ROARR.write = buffer.write;

// 1. Roarr formats and dispatches structured log messages containing context, message, sequence, and version
{
  buffer.clear();
  Roarr('user login attempt');

  const messages = buffer.getMessages();
  assert.equal(messages.length, 1);

  const entry = messages[0];
  assert.equal(entry.message, 'user login attempt');
  assert.deepEqual(entry.context, {});
  assert.equal(typeof entry.sequence, 'number');
  assert.equal(typeof entry.time, 'number');
  assert.equal(entry.version, '1.0.0');
}

// 2. Roarr interpolates sprintf placeholder specifiers into message strings with positional arguments
{
  buffer.clear();
  Roarr('User %s completed %d tasks with ratio %.2f and hex %x', 'Alice', 42, 3.14159, 255);
  Roarr('JSON payload: %j', { active: true, count: 5 });

  const messages = buffer.getMessages();
  assert.equal(messages.length, 2);
  assert.equal(messages[0].message, 'User Alice completed 42 tasks with ratio 3.14 and hex ff');
  assert.equal(messages[1].message, 'JSON payload: {"active":true,"count":5}');
}

// 3. Roarr accepts a context object as the first argument and attaches it to the log record
{
  buffer.clear();
  Roarr({ traceId: 'trace-101', service: 'payment' }, 'processing payment for order %s', 'ord-99');

  const messages = buffer.getMessages();
  assert.equal(messages.length, 1);
  assert.equal(messages[0].message, 'processing payment for order ord-99');
  assert.equal(messages[0].context.traceId, 'trace-101');
  assert.equal(messages[0].context.service, 'payment');
}

// 4. Roarr.child creates a child logger that inherits and merges parent context properties
{
  buffer.clear();
  const parentLogger = Roarr.child({ service: 'auth', env: 'production' });
  const childLogger = parentLogger.child({ endpoint: '/v1/login' });

  childLogger({ userId: 'u-55' }, 'token issued');

  const messages = buffer.getMessages();
  assert.equal(messages.length, 1);
  assert.equal(messages[0].message, 'token issued');
  assert.deepEqual(messages[0].context, {
    service: 'auth',
    env: 'production',
    endpoint: '/v1/login',
    userId: 'u-55',
  });
}

// 5. Roarr.child with a transform function modifies log payload before dispatching
{
  buffer.clear();
  const auditLogger = Roarr.child((msg) => ({
    ...msg,
    message: `[AUDIT] ${msg.message}`,
    context: {
      ...msg.context,
      audited: true,
    },
  }));

  auditLogger({ action: 'delete_account' }, 'account was deleted');

  const messages = buffer.getMessages();
  assert.equal(messages.length, 1);
  assert.equal(messages[0].message, '[AUDIT] account was deleted');
  assert.equal(messages[0].context.action, 'delete_account');
  assert.equal(messages[0].context.audited, true);
}

// 6. Roarr provides severity methods (trace, debug, info, warn, error, fatal) that set numeric logLevel in context
{
  buffer.clear();
  Roarr.trace('trace event');
  Roarr.debug('debug event');
  Roarr.info('info event');
  Roarr.warn('warn event');
  Roarr.error('error event');
  Roarr.fatal('fatal event');

  const messages = buffer.getMessages();
  assert.equal(messages.length, 6);
  assert.equal(messages[0].context.logLevel, logLevels.trace);
  assert.equal(messages[0].context.logLevel, 10);
  assert.equal(messages[1].context.logLevel, logLevels.debug);
  assert.equal(messages[1].context.logLevel, 20);
  assert.equal(messages[2].context.logLevel, logLevels.info);
  assert.equal(messages[2].context.logLevel, 30);
  assert.equal(messages[3].context.logLevel, logLevels.warn);
  assert.equal(messages[3].context.logLevel, 40);
  assert.equal(messages[4].context.logLevel, logLevels.error);
  assert.equal(messages[4].context.logLevel, 50);
  assert.equal(messages[5].context.logLevel, logLevels.fatal);
  assert.equal(messages[5].context.logLevel, 60);
}

// 7. Roarr.getContext returns the current accumulated context object
{
  const scoped = createScopedLogger({ app: 'web-api', region: 'us-east-1' });
  assert.deepEqual(scoped.getContext(), {
    app: 'web-api',
    region: 'us-east-1',
  });

  const nested = scoped.child({ cluster: 'primary' });
  assert.deepEqual(nested.getContext(), {
    app: 'web-api',
    region: 'us-east-1',
    cluster: 'primary',
  });
}

// 8. ROARR.write receives serialized JSON log strings to allow custom transport routing
{
  let capturedRaw = null;
  const originalWrite = ROARR.write;
  ROARR.write = (raw) => {
    capturedRaw = raw;
  };

  Roarr({ testRoute: true }, 'transport check');

  assert.equal(typeof capturedRaw, 'string');
  const parsed = JSON.parse(capturedRaw);
  assert.equal(parsed.message, 'transport check');
  assert.equal(parsed.context.testRoute, true);

  ROARR.write = originalWrite;
}

// 9. Roarr throws a TypeError when context is provided and message is not a string
{
  assert.throws(() => Roarr({ key: 'val' }, 12345), TypeError);
  assert.throws(() => Roarr({ key: 'val' }, null), TypeError);
  assert.throws(() => Roarr({ key: 'val' }, undefined), TypeError);
  assert.throws(() => Roarr({ key: 'val' }, {}), TypeError);
}

console.log('Contract tests passed successfully.');