roarr 2.15.4: default

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 roarr.default in pkg:npm/roarr@2.15.4
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/roarr@2.15.4
Demonstrate these symbols/APIs:
  - roarr.default

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:3e7607f114a334c79208cb0f475e8b0812167063660f2f5c81f188b0f7a7edf4","contract":["roarr.default formats and dispatches structured log messages containing context, message, sequence, and version","roarr.default interpolates sprintf placeholder specifiers into message strings with positional arguments","roarr.default accepts a context object as the first argument and attaches it to the log record","roarr.default.child creates a child logger that inherits and merges parent context properties","roarr.default.child with a transform function modifies log payload before dispatching","roarr.default provides severity methods (trace, debug, info, warn, error, fatal) that set numeric logLevel in context","roarr.default.getContext returns the current accumulated context object","roarr.default.adopt runs an asynchronous routine within domain context and attaches context to nested logs","roarr.default throws a TypeError when context is provided and message is not a string"],"goal":"verify roarr.default in pkg:npm/roarr@2.15.4","kind":"HOW","packages":["pkg:npm/roarr@2.15.4"],"schemaVersion":1,"symbols":["roarr.default"]},"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","symbols":["roarr.default"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-roarr-default",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-roarr-default",
      "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",
      "dependencies": {
        "es-errors": "^1.3.0"
      },
      "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-default",
  "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 roarr.default in pkg:npm/roarr@2.15.4",
  "kind": "HOW",
  "packages": [
    "pkg:npm/roarr@2.15.4"
  ],
  "symbols": [
    "roarr.default"
  ]
}

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 child logger with preset context.
 * @param {object} initialContext - Initial context properties.
 * @returns {Function} Scoped Roarr child logger.
 */
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.default formats and dispatches structured log messages containing context, message, sequence, and version
{
  buffer.clear();
  Roarr('system initialized');

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

  const entry = messages[0];
  assert.equal(entry.message, 'system initialized');
  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.default interpolates sprintf placeholder specifiers into message strings with positional arguments
{
  buffer.clear();
  Roarr('Worker %s completed %d jobs in %.1f sec', 'worker-1', 42, 1.5);
  Roarr('State: %j', { status: 'healthy' });

  const messages = buffer.getMessages();
  assert.equal(messages.length, 2);
  assert.equal(messages[0].message, 'Worker worker-1 completed 42 jobs in 1.5 sec');
  assert.equal(messages[1].message, 'State: {"status":"healthy"}');
}

// 3. roarr.default accepts a context object as the first argument and attaches it to the log record
{
  buffer.clear();
  Roarr({ traceId: 'tr-987', component: 'gateway' }, 'handling request for %s', '/health');

  const messages = buffer.getMessages();
  assert.equal(messages.length, 1);
  assert.equal(messages[0].message, 'handling request for /health');
  assert.equal(messages[0].context.traceId, 'tr-987');
  assert.equal(messages[0].context.component, 'gateway');
}

// 4. roarr.default.child creates a child logger that inherits and merges parent context properties
{
  buffer.clear();
  const parentLogger = Roarr.child({ app: 'sample-app', env: 'test' });
  const childLogger = parentLogger.child({ module: 'worker' });

  childLogger({ jobId: 'job-12' }, 'job executed');

  const messages = buffer.getMessages();
  assert.equal(messages.length, 1);
  assert.equal(messages[0].message, 'job executed');
  assert.deepEqual(messages[0].context, {
    app: 'sample-app',
    env: 'test',
    module: 'worker',
    jobId: 'job-12',
  });
}

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

  transformer({ tag: 'event' }, 'raw event message');

  const messages = buffer.getMessages();
  assert.equal(messages.length, 1);
  assert.equal(messages[0].message, '[PREFIX] raw event message');
  assert.equal(messages[0].context.tag, 'event');
  assert.equal(messages[0].context.transformed, true);
}

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

  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.default.getContext returns the current accumulated context object
{
  const scoped = createScopedLogger({ service: 'order-api', version: '2.0.0' });
  assert.deepEqual(scoped.getContext(), {
    service: 'order-api',
    version: '2.0.0',
  });

  const nested = scoped.child({ region: 'eu-west-1' });
  assert.deepEqual(nested.getContext(), {
    service: 'order-api',
    version: '2.0.0',
    region: 'eu-west-1',
  });
}

// 8. roarr.default.adopt runs an asynchronous routine within domain context and attaches context to nested logs
{
  buffer.clear();
  await Roarr.adopt(async () => {
    Roarr('operation inside domain');
  }, { correlationId: 'corr-xyz' });

  const messages = buffer.getMessages();
  assert.equal(messages.length, 1);
  assert.equal(messages[0].message, 'operation inside domain');
  assert.equal(messages[0].context.correlationId, 'corr-xyz');
}

// 9. roarr.default 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.');