hookified 2.2.0

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/hookified@2.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/hookified@2.2.0
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:be56285dedb71ab77654df54ba06ec055ffb3a35c2b6b5cd7a9607948b36ecfe","constraints":{"executionContext":"node"},"contract":["Hookified registers lifecycle hooks with onHook and executes them during hook calls","Hookified supports beforeHook and afterHook convenience methods with prefixing","Hookified onceHook executes registered handlers exactly once","Hookified hookSync executes synchronous hook handlers","Hookified prependHook executes registered handlers before previously registered handlers","Hookified enforceBeforeAfter option rejects hook registration without before or after prefix","Hookified throwOnHookError option causes hook invocation to reject when a handler throws","Hookified inherits Eventified to register listeners with on and emit events","ParallelHook executes hook functions concurrently and delivers settled results to final handler","WaterfallHook executes hook functions sequentially passing accumulated context to final handler"],"goal":"verify pkg:npm/hookified@2.2.0","kind":"HOW","packages":["pkg:npm/hookified@2.2.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/hookified@2.2.0"],"schemaVersion":1,"subject":"pkg:npm/hookified@2.2.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-hookified",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-hookified",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "hookified": "2.2.0"
      }
    },
    "node_modules/hookified": {
      "version": "2.2.0",
      "resolved": "https://registry.npmjs.org/hookified/-/hookified-2.2.0.tgz",
      "integrity": "sha512-p/LgFzRN5FeoD3DLS6bkUapeye6E4SI6yJs6KetENd18S+FBthqYq2amJUWpt5z0EQwwHemidjY5OqJGEKm5uA==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-hookified",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for hookified@2.2.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "hookified": "2.2.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/hookified@2.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/hookified@2.2.0"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

'use strict';

const { Hookified, Hook, Eventified, ParallelHook, WaterfallHook } = require('hookified');

/**
 * Creates and configures a Hookified lifecycle manager instance.
 *
 * @param {object} [options] - Options for Hookified instance.
 * @returns {Hookified}
 */
function createHookManager(options) {
  return new Hookified(options);
}

/**
 * Executes a named hook with arguments on the provided Hookified instance.
 *
 * @param {Hookified} manager - Hookified instance.
 * @param {string} hookName - Name of the hook.
 * @param {...*} args - Arguments to pass to hook handlers.
 * @returns {Promise<void>}
 */
async function triggerHook(manager, hookName, ...args) {
  return manager.hook(hookName, ...args);
}

/**
 * Executes a named hook synchronously on the provided Hookified instance.
 *
 * @param {Hookified} manager - Hookified instance.
 * @param {string} hookName - Name of the hook.
 * @param {...*} args - Arguments to pass to hook handlers.
 * @returns {void}
 */
function triggerHookSync(manager, hookName, ...args) {
  return manager.hookSync(hookName, ...args);
}

module.exports = {
  Hookified,
  Hook,
  Eventified,
  ParallelHook,
  WaterfallHook,
  createHookManager,
  triggerHook,
  triggerHookSync
};

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  Hookified,
  Hook,
  Eventified,
  ParallelHook,
  WaterfallHook,
  createHookManager,
  triggerHook,
  triggerHookSync
} = require('../src/index.js');

async function testAll() {
  // 1. Export verification
  assert.equal(typeof Hookified, 'function', 'Hookified export must be a constructor function');
  assert.equal(typeof Hook, 'function', 'Hook export must be a constructor function');
  assert.equal(typeof Eventified, 'function', 'Eventified export must be a constructor function');
  assert.equal(typeof ParallelHook, 'function', 'ParallelHook export must be a constructor function');
  assert.equal(typeof WaterfallHook, 'function', 'WaterfallHook export must be a constructor function');
  assert.equal(typeof createHookManager, 'function', 'createHookManager helper must be a function');
  assert.equal(typeof triggerHook, 'function', 'triggerHook helper must be a function');
  assert.equal(typeof triggerHookSync, 'function', 'triggerHookSync helper must be a function');

  // 2. Hookified registers lifecycle hooks with onHook and executes them during hook calls
  const h1 = createHookManager();
  let executedH1 = false;
  h1.onHook('lifecycle:init', (payload) => {
    assert.equal(payload.status, 'started');
    executedH1 = true;
  });
  await triggerHook(h1, 'lifecycle:init', { status: 'started' });
  assert.equal(executedH1, true, 'onHook handler must execute when hook is triggered');

  // 3. Hookified supports beforeHook and afterHook convenience methods with prefixing
  const h2 = createHookManager();
  const stages = [];
  h2.onHook('before:action', () => { stages.push('before'); });
  h2.onHook('after:action', () => { stages.push('after'); });
  await h2.beforeHook('action');
  await h2.afterHook('action');
  assert.deepEqual(stages, ['before', 'after'], 'beforeHook and afterHook should call prefixed handlers');

  // 4. Hookified onceHook executes registered handlers exactly once
  const h3 = createHookManager();
  let onceCalls = 0;
  h3.onceHook({
    event: 'single-run',
    handler: () => {
      onceCalls++;
    }
  });
  await triggerHook(h3, 'single-run');
  await triggerHook(h3, 'single-run');
  assert.equal(onceCalls, 1, 'onceHook handler must only execute once across multiple triggers');

  // 5. Hookified hookSync executes synchronous hook handlers
  const h4 = createHookManager();
  let syncTotal = 0;
  h4.onHook('compute', (delta) => {
    syncTotal += delta;
  });
  triggerHookSync(h4, 'compute', 15);
  assert.equal(syncTotal, 15, 'hookSync must synchronously execute registered handlers');

  // 6. Hookified prependHook executes registered handlers before previously registered handlers
  const h5 = createHookManager();
  const sequence = [];
  h5.onHook('step', () => { sequence.push('second'); });
  h5.prependHook({
    event: 'step',
    handler: () => { sequence.push('first'); }
  });
  await triggerHook(h5, 'step');
  assert.deepEqual(sequence, ['first', 'second'], 'prependHook handler must execute before normal handlers');

  // 7. Hookified enforceBeforeAfter option rejects hook registration without before or after prefix
  const h6 = createHookManager({ enforceBeforeAfter: true });
  assert.throws(
    () => {
      h6.onHook('customAction', () => {});
    },
    (err) => err instanceof Error,
    'enforceBeforeAfter must throw an error if hook name lacks before: or after: prefix'
  );
  assert.doesNotThrow(() => {
    h6.onHook('before:customAction', () => {});
    h6.onHook('after:customAction', () => {});
  });

  // 8. Hookified throwOnHookError option causes hook invocation to reject when a handler throws
  const h7 = createHookManager({ throwOnHookError: true });
  h7.onHook('failing-step', () => {
    throw new Error('step failed');
  });
  await assert.rejects(
    async () => {
      await triggerHook(h7, 'failing-step');
    },
    {
      name: 'Error',
      message: 'failing-step: step failed'
    },
    'throwOnHookError must cause hook trigger to reject when handler throws'
  );

  // 9. Hookified inherits Eventified to register listeners with on and emit events
  const h8 = createHookManager();
  let eventPayload = null;
  h8.on('state-change', (data) => {
    eventPayload = data;
  });
  const emitted = h8.emit('state-change', { active: true });
  assert.equal(emitted, true, 'emit must return true when listeners exist');
  assert.deepEqual(eventPayload, { active: true }, 'registered event listener must receive emitted data');

  // 10. ParallelHook executes hook functions concurrently and delivers settled results to final handler
  let parallelResults = null;
  const pHook = new ParallelHook('parallel:task', (context) => {
    parallelResults = context;
  });
  pHook.addHook(async (ctx) => ctx.initialArgs * 2);
  pHook.addHook(async (ctx) => ctx.initialArgs + 10);
  const h9 = createHookManager();
  h9.onHook(pHook);
  await triggerHook(h9, 'parallel:task', 5);
  assert.ok(parallelResults, 'ParallelHook final handler must be called');
  assert.equal(parallelResults.initialArgs, 5, 'ParallelHook must preserve initialArgs');

  // 11. WaterfallHook executes hook functions sequentially passing accumulated context to final handler
  let waterfallResults = null;
  const wHook = new WaterfallHook('waterfall:task', (context) => {
    waterfallResults = context;
  });
  wHook.addHook((ctx) => (ctx.initialArgs || 0) + 10);
  wHook.addHook((ctx) => ctx.results[0].result * 3);
  const h10 = createHookManager();
  h10.onHook(wHook);
  await triggerHook(h10, 'waterfall:task', 5);
  assert.ok(waterfallResults, 'WaterfallHook final handler must be called');
  assert.equal(waterfallResults.results[1].result, 45, 'WaterfallHook must chain intermediate results');

  console.log('All hookified contract tests passed successfully.');
}

testAll().catch((err) => {
  console.error('Contract test failure:', err);
  process.exit(1);
});