@emnapi/runtime 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/runtime@1.11.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40emnapi/runtime@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:982336ac53abb99440cbe5172fed7561fe0e3cf66b94f1df4e266fad03ad6410","contract":["assert version is exported as a string matching 1.11.1","assert NODE_API version constants define standard Node-API compatibility bounds","assert getDefaultContext returns a shared Context instance with runtime version metadata","assert createContext initializes an independent Context with HandleScope lifecycle support","assert Context openScope and closeScope correctly create and dispose handle scopes","assert Context ensureHandle wraps JavaScript values into Handle instances with type inspections","assert External wraps pointers and getExternalValue extracts the numeric pointer value","assert isReferenceType accurately distinguishes object and function references from primitives"],"goal":"verify pkg:npm/%40emnapi/runtime@1.11.1","kind":"HOW","packages":["pkg:npm/%40emnapi/runtime@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/runtime@1.11.1"],"schemaVersion":1,"subject":"pkg:npm/%40emnapi/runtime@1.11.1","verifierAdapter":"node-typescript@1"}

import {
  version,
  NODE_API_DEFAULT_MODULE_API_VERSION,
  NODE_API_SUPPORTED_VERSION_MIN,
  NODE_API_SUPPORTED_VERSION_MAX,
  NAPI_VERSION_EXPERIMENTAL,
  getDefaultContext,
  createContext,
  Context,
  External,
  isExternal,
  getExternalValue,
  isReferenceType
} from '@emnapi/runtime';

/**
 * Returns runtime version string.
 * @returns {string}
 */
export function getRuntimeVersion() {
  return version;
}

/**
 * Returns Node-API supported version bounds.
 * @returns {{ min: number, default: number, max: number, experimental: number }}
 */
export function getNodeApiVersionBounds() {
  return {
    min: NODE_API_SUPPORTED_VERSION_MIN,
    default: NODE_API_DEFAULT_MODULE_API_VERSION,
    max: NODE_API_SUPPORTED_VERSION_MAX,
    experimental: NAPI_VERSION_EXPERIMENTAL
  };
}

/**
 * Creates and returns an isolated emnapi Context.
 * @param {object} [options]
 * @returns {Context}
 */
export function createIsolatedContext(options) {
  return createContext(options);
}

/**
 * Creates a Handle for a value within a scoped execution callback.
 * @param {Context} ctx
 * @param {any} value
 * @returns {{ id: number, value: any, isObject: boolean }}
 */
export function wrapValueInScope(ctx, value) {
  const scope = ctx.openScope();
  try {
    const handle = ctx.ensureHandle(value);
    return {
      id: handle.id,
      value: handle.value,
      isObject: handle.isObject()
    };
  } finally {
    ctx.closeScope(undefined, scope);
  }
}

/**
 * Wraps a pointer into an External instance.
 * @param {number|bigint} ptr
 * @returns {External}
 */
export function createExternalPointer(ptr) {
  return new External(ptr);
}

/**
 * Extracts numeric pointer from External object.
 * @param {External} external
 * @returns {number|bigint}
 */
export function extractPointerValue(external) {
  return getExternalValue(external);
}

export {
  version,
  NODE_API_DEFAULT_MODULE_API_VERSION,
  NODE_API_SUPPORTED_VERSION_MIN,
  NODE_API_SUPPORTED_VERSION_MAX,
  NAPI_VERSION_EXPERIMENTAL,
  getDefaultContext,
  createContext,
  Context,
  External,
  isExternal,
  getExternalValue,
  isReferenceType
};

{
  "name": "sample-emnapi-runtime-verify",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-emnapi-runtime-verify",
      "version": "1.0.0",
      "dependencies": {
        "@emnapi/runtime": "1.11.1"
      }
    },
    "node_modules/@emnapi/runtime": {
      "version": "1.11.1",
      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.1.tgz",
      "integrity": "sha512-vgj7R3y3Wgx24IQaGPA/R6YFXLHVMOZ0uVEyIQPaWs+rd1AzfEMXlAC22FYwO1XkKR6NPsq7mUandH8oIRdZFw==",
      "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-runtime-verify",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "@emnapi/runtime": "1.11.1"
  }
}

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

import assert from 'node:assert/strict';
import {
  version,
  NODE_API_DEFAULT_MODULE_API_VERSION,
  NODE_API_SUPPORTED_VERSION_MIN,
  NODE_API_SUPPORTED_VERSION_MAX,
  NAPI_VERSION_EXPERIMENTAL,
  getDefaultContext,
  createContext,
  Context,
  External,
  isExternal,
  getExternalValue,
  isReferenceType,
  getRuntimeVersion,
  getNodeApiVersionBounds,
  createIsolatedContext,
  wrapValueInScope,
  createExternalPointer,
  extractPointerValue
} from '../index.mjs';

// 1. assert version is exported as a string matching 1.11.1
{
  assert.strictEqual(typeof version, 'string');
  assert.strictEqual(version, '1.11.1');
  assert.strictEqual(getRuntimeVersion(), '1.11.1');
}

// 2. assert NODE_API version constants define standard Node-API compatibility bounds
{
  assert.strictEqual(NODE_API_SUPPORTED_VERSION_MIN, 1);
  assert.strictEqual(NODE_API_DEFAULT_MODULE_API_VERSION, 8);
  assert.strictEqual(NODE_API_SUPPORTED_VERSION_MAX, 10);
  assert.strictEqual(NAPI_VERSION_EXPERIMENTAL, 2147483647);

  const bounds = getNodeApiVersionBounds();
  assert.deepStrictEqual(bounds, {
    min: 1,
    default: 8,
    max: 10,
    experimental: 2147483647
  });
}

// 3. assert getDefaultContext returns a shared Context instance with runtime version metadata
{
  const defaultCtx = getDefaultContext();
  assert.ok(defaultCtx instanceof Context);

  const versions = defaultCtx.getRuntimeVersions();
  assert.strictEqual(versions.version, '1.11.1');
  assert.strictEqual(versions.NODE_API_DEFAULT_MODULE_API_VERSION, 8);
  assert.strictEqual(versions.NODE_API_SUPPORTED_VERSION_MAX, 10);
  assert.strictEqual(versions.NAPI_VERSION_EXPERIMENTAL, 2147483647);
  assert.strictEqual(typeof defaultCtx.feature, 'object');
  assert.strictEqual(typeof defaultCtx.feature.supportReflect, 'boolean');
}

// 4. assert createContext initializes an independent Context with HandleScope lifecycle support
{
  const ctx = createIsolatedContext();
  assert.ok(ctx instanceof Context);
  assert.notStrictEqual(ctx, getDefaultContext());
  assert.strictEqual(typeof ctx.openScope, 'function');
  assert.strictEqual(typeof ctx.closeScope, 'function');
  assert.strictEqual(typeof ctx.ensureHandle, 'function');
}

// 5. assert Context openScope and closeScope correctly create and dispose handle scopes
{
  const ctx = createContext();
  const rootScope = ctx.getCurrentScope();
  assert.ok(rootScope);
  assert.strictEqual(rootScope.id, 0);

  const scope = ctx.openScope();
  assert.ok(scope);
  assert.strictEqual(ctx.getCurrentScope(), scope);
  assert.strictEqual(scope.parent, rootScope);

  const nestedScope = ctx.openScope();
  assert.ok(nestedScope);
  assert.strictEqual(ctx.getCurrentScope(), nestedScope);
  assert.strictEqual(nestedScope.parent, scope);

  ctx.closeScope(undefined, nestedScope);
  assert.strictEqual(ctx.getCurrentScope(), scope);

  ctx.closeScope(undefined, scope);
  assert.strictEqual(ctx.getCurrentScope(), rootScope);
}

// 6. assert Context ensureHandle wraps JavaScript values into Handle instances with type inspections
{
  const ctx = createContext();
  const wrapped = wrapValueInScope(ctx, { name: 'emnapi', active: true });
  assert.ok(wrapped.id >= 6);
  assert.strictEqual(wrapped.value.name, 'emnapi');
  assert.strictEqual(wrapped.value.active, true);
  assert.strictEqual(wrapped.isObject, true);

  const scope = ctx.openScope();
  const numHandle = ctx.ensureHandle(42);
  assert.strictEqual(numHandle.isNumber(), true);
  assert.strictEqual(numHandle.isString(), false);

  const strHandle = ctx.ensureHandle('test');
  assert.strictEqual(strHandle.isString(), true);
  assert.strictEqual(strHandle.isNumber(), false);

  const fnHandle = ctx.ensureHandle(() => {});
  assert.strictEqual(fnHandle.isFunction(), true);
  ctx.closeScope(undefined, scope);
}

// 7. assert External wraps pointers and getExternalValue extracts the numeric pointer value
{
  const ptr = 0x1234abcd;
  const external = createExternalPointer(ptr);
  assert.strictEqual(isExternal(external), true);
  assert.strictEqual(isExternal({}), false);
  assert.strictEqual(isExternal(null), false);
  assert.strictEqual(extractPointerValue(external), ptr);
  assert.strictEqual(getExternalValue(new External(9999)), 9999);
}

// 8. assert isReferenceType accurately distinguishes object and function references from primitives
{
  assert.strictEqual(isReferenceType({}), true);
  assert.strictEqual(isReferenceType([]), true);
  assert.strictEqual(isReferenceType(() => {}), true);
  assert.strictEqual(isReferenceType(new Date()), true);

  assert.strictEqual(isReferenceType(null), false);
  assert.strictEqual(isReferenceType(undefined), false);
  assert.strictEqual(isReferenceType(123), false);
  assert.strictEqual(isReferenceType('str'), false);
  assert.strictEqual(isReferenceType(true), false);
  assert.strictEqual(isReferenceType(Symbol('s')), false);
}

console.log('All @emnapi/runtime contract assertions passed.');