@emnapi/core 1.11.1

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/%40emnapi/core@1.11.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40emnapi/core@1.11.1

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:81184593f8e2816b85bf21671f6dd0e195cb780231eecec7c2e519d1ef0df806","contract":["version export matches package version string 1.11.1","isSharedArrayBuffer returns true for SharedArrayBuffer and false for ArrayBuffer or other objects","isTrapError identifies WebAssembly.RuntimeError instances and rejects standard Errors","createInstanceProxy proxies exports and custom memory on WebAssembly instances idempotently","createNapiModule initializes module structure with childThread and emnapi helper functions","loadNapiModuleSync throws TypeError when provided with invalid napiModule","MessageHandler validates required onLoad and postMessage options in constructor","WASIThreads validates that wasi instance is provided and exposes thread-spawn imports","ThreadManager initializes child thread configuration with worker pool defaults"],"goal":"verify pkg:npm/%40emnapi/core@1.11.1","kind":"HOW","packages":["pkg:npm/%40emnapi/core@1.11.1"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/%40emnapi/core@1.11.1"],"schemaVersion":1,"subject":"pkg:npm/%40emnapi/core@1.11.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-emnapi-core",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-emnapi-core",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@emnapi/core": "1.11.1"
      }
    },
    "node_modules/@emnapi/core": {
      "version": "1.11.1",
      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.1.tgz",
      "integrity": "sha512-RSvbQmHzdKzNsLYa/wHrbc3KN4sYLKAdPZxqiM2HATqv/SBk2/ENSHpvXGaLOMcsAyz0poEGqkmmKYG3OWiJEQ==",
      "license": "MIT",
      "dependencies": {
        "@emnapi/wasi-threads": "1.2.2",
        "tslib": "^2.4.0"
      }
    },
    "node_modules/@emnapi/wasi-threads": {
      "version": "1.2.2",
      "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.2.tgz",
      "integrity": "sha512-c95qOXkHdydNKhscBTebqEC1CVAZpyqOfVfBzQ1qgzyl3gfeldUjIggDbIZgDKsHLgnsM+igH7TJ/eAasaVuMA==",
      "license": "MIT",
      "dependencies": {
        "tslib": "^2.4.0"
      }
    },
    "node_modules/tslib": {
      "version": "2.8.1",
      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
      "license": "0BSD"
    }
  }
}

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

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40emnapi/core@1.11.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40emnapi/core@1.11.1"
  ]
}

import {
  version,
  isSharedArrayBuffer,
  isTrapError,
  createInstanceProxy,
  createNapiModule,
  loadNapiModuleSync,
  MessageHandler,
  ThreadManager,
  WASIThreads
} from '@emnapi/core';

/**
 * Returns the version string of @emnapi/core.
 * @returns {string} Version identifier.
 */
export function getCoreVersion() {
  return version;
}

/**
 * Checks whether the given buffer value is a SharedArrayBuffer.
 * @param {*} buffer - Value to test.
 * @returns {boolean} True if the value is a SharedArrayBuffer.
 */
export function checkSharedArrayBuffer(buffer) {
  return isSharedArrayBuffer(buffer);
}

/**
 * Checks whether the given error is a WebAssembly.RuntimeError trap.
 * @param {*} error - Error to test.
 * @returns {boolean} True if the error is a WebAssembly.RuntimeError.
 */
export function checkTrapError(error) {
  return isTrapError(error);
}

/**
 * Wraps a WebAssembly instance with an optional custom memory export.
 * @param {WebAssembly.Instance} instance - Target WebAssembly instance.
 * @param {WebAssembly.Memory} [memory] - Optional custom memory.
 * @returns {WebAssembly.Instance} Proxied WebAssembly instance.
 */
export function wrapInstanceProxy(instance, memory) {
  return createInstanceProxy(instance, memory);
}

/**
 * Initializes a child thread N-API module descriptor.
 * @param {object} options - Options for creating N-API module.
 * @returns {object} Initialized NapiModule object.
 */
export function initChildNapiModule(options = {}) {
  return createNapiModule({
    childThread: true,
    postMessage: () => {},
    ...options
  });
}

/**
 * Initializes a child WASIThreads instance.
 * @param {object} wasi - WASI instance.
 * @param {object} options - Additional options.
 * @returns {WASIThreads} WASIThreads instance.
 */
export function createChildWasiThreads(wasi, options = {}) {
  return new WASIThreads({
    wasi,
    childThread: true,
    postMessage: () => {},
    ...options
  });
}

/**
 * Initializes a child thread manager instance.
 * @param {object} options - Thread manager options.
 * @returns {ThreadManager} ThreadManager instance.
 */
export function createChildThreadManager(options = {}) {
  return new ThreadManager({
    childThread: true,
    ...options
  });
}

export {
  version,
  isSharedArrayBuffer,
  isTrapError,
  createInstanceProxy,
  createNapiModule,
  loadNapiModuleSync,
  MessageHandler,
  ThreadManager,
  WASIThreads
};

import assert from 'node:assert/strict';
import {
  getCoreVersion,
  checkSharedArrayBuffer,
  checkTrapError,
  wrapInstanceProxy,
  initChildNapiModule,
  createChildWasiThreads,
  createChildThreadManager,
  version,
  isSharedArrayBuffer,
  isTrapError,
  createInstanceProxy,
  createNapiModule,
  loadNapiModuleSync,
  MessageHandler,
  ThreadManager,
  WASIThreads
} from '../src/index.mjs';

async function main() {
  // 1. version export matches package version string 1.11.1
  assert.strictEqual(typeof version, 'string', 'version must be a string');
  assert.strictEqual(version, '1.11.1', 'version must match 1.11.1');
  assert.strictEqual(getCoreVersion(), '1.11.1', 'helper getCoreVersion must match 1.11.1');

  // 2. isSharedArrayBuffer returns true for SharedArrayBuffer and false for ArrayBuffer or other objects
  assert.strictEqual(isSharedArrayBuffer(new SharedArrayBuffer(16)), true, 'SharedArrayBuffer must return true');
  assert.strictEqual(isSharedArrayBuffer(new ArrayBuffer(16)), false, 'ArrayBuffer must return false');
  assert.strictEqual(isSharedArrayBuffer(new Uint8Array(16)), false, 'Uint8Array must return false');
  assert.strictEqual(isSharedArrayBuffer(null), false, 'null must return false');
  assert.strictEqual(isSharedArrayBuffer({}), false, 'plain object must return false');
  assert.strictEqual(checkSharedArrayBuffer(new SharedArrayBuffer(32)), true, 'helper checkSharedArrayBuffer must return true for SharedArrayBuffer');
  assert.strictEqual(checkSharedArrayBuffer(new ArrayBuffer(32)), false, 'helper checkSharedArrayBuffer must return false for ArrayBuffer');

  // 3. isTrapError identifies WebAssembly.RuntimeError instances and rejects standard Errors
  assert.strictEqual(isTrapError(new WebAssembly.RuntimeError('unreachable')), true, 'WebAssembly.RuntimeError must be recognized as trap');
  assert.strictEqual(isTrapError(new Error('general error')), false, 'Error must not be recognized as trap');
  assert.strictEqual(isTrapError(new TypeError('type error')), false, 'TypeError must not be recognized as trap');
  assert.strictEqual(isTrapError(null), false, 'null must not be recognized as trap');
  assert.strictEqual(checkTrapError(new WebAssembly.RuntimeError('out of bounds')), true, 'helper checkTrapError must return true for RuntimeError');
  assert.strictEqual(checkTrapError(new Error('runtime')), false, 'helper checkTrapError must return false for Error');

  // 4. createInstanceProxy proxies exports and custom memory on WebAssembly instances idempotently
  const mockInstance = { exports: { val: 42, compute: () => 84 } };
  const customMemory = new WebAssembly.Memory({ initial: 1 });
  const proxy = wrapInstanceProxy(mockInstance, customMemory);
  assert.strictEqual(proxy.exports.val, 42, 'proxied exports must retain properties');
  assert.strictEqual(proxy.exports.compute(), 84, 'proxied exports must retain functions');
  assert.strictEqual(proxy.exports.memory, customMemory, 'proxied exports must expose supplied custom memory');
  assert.strictEqual(createInstanceProxy(proxy), proxy, 'createInstanceProxy must be idempotent on already proxied instance');

  // 5. createNapiModule initializes module structure with childThread and emnapi helper functions
  const mod = initChildNapiModule();
  assert.strictEqual(mod.childThread, true, 'childThread flag must be true');
  assert.strictEqual(mod.loaded, false, 'loaded flag must initially be false');
  assert.ok(mod.imports && typeof mod.imports === 'object', 'module must contain imports object');
  assert.ok(mod.imports.env && mod.imports.napi && mod.imports.emnapi, 'imports must contain env, napi, and emnapi namespaces');
  assert.strictEqual(typeof mod.init, 'function', 'mod.init must be a function');
  assert.strictEqual(typeof mod.emnapi.syncMemory, 'function', 'emnapi.syncMemory must be a function');
  assert.strictEqual(typeof mod.emnapi.getMemoryAddress, 'function', 'emnapi.getMemoryAddress must be a function');
  assert.strictEqual(typeof mod.emnapi.addSendListener, 'function', 'emnapi.addSendListener must be a function');

  // 6. loadNapiModuleSync throws TypeError when provided with invalid napiModule
  assert.throws(
    () => loadNapiModuleSync(null),
    {
      name: 'TypeError',
      message: 'Invalid napiModule'
    },
    'loadNapiModuleSync must throw TypeError on null module'
  );
  assert.throws(
    () => loadNapiModuleSync(undefined),
    {
      name: 'TypeError',
      message: 'Invalid napiModule'
    },
    'loadNapiModuleSync must throw TypeError on undefined module'
  );

  // 7. MessageHandler validates required onLoad and postMessage options in constructor
  assert.throws(
    () => new MessageHandler({}),
    {
      name: 'TypeError',
      message: 'options.onLoad is not a function'
    },
    'MessageHandler constructor must require options.onLoad'
  );
  assert.throws(
    () => new MessageHandler({ onLoad: () => ({}) }),
    {
      name: 'TypeError',
      message: 'options.postMessage is not a function'
    },
    'MessageHandler constructor must require options.postMessage'
  );
  const mh = new MessageHandler({ onLoad: () => ({}), postMessage: () => {} });
  assert.ok(mh instanceof MessageHandler, 'instantiated object must be an instance of MessageHandler');
  assert.strictEqual(typeof mh.handle, 'function', 'MessageHandler must have a handle method');

  // 8. WASIThreads validates that wasi instance is provided and exposes thread-spawn imports
  assert.throws(
    () => new WASIThreads({ childThread: true }),
    {
      name: 'TypeError',
      message: 'WASIThreads(): options.wasi is not provided'
    },
    'WASIThreads constructor must throw when wasi option is missing'
  );
  const mockWasi = { initialize() {}, start() { return 0; } };
  const wt = createChildWasiThreads(mockWasi);
  assert.strictEqual(wt.childThread, true, 'WASIThreads childThread must be set');
  const importObj = wt.getImportObject();
  assert.ok(importObj.wasi && typeof importObj.wasi['thread-spawn'] === 'function', 'WASIThreads must expose thread-spawn import');

  // 9. ThreadManager initializes child thread configuration with worker pool defaults
  const tm = createChildThreadManager();
  assert.ok(tm instanceof ThreadManager, 'instantiated object must be an instance of ThreadManager');
  assert.strictEqual(tm.shouldPreloadWorkers(), false, 'shouldPreloadWorkers must return false for child thread');
  assert.strictEqual(typeof tm.terminateAllThreads, 'function', 'ThreadManager must provide terminateAllThreads method');

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

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