@keyv/bigmap 1.3.1: createKeyv

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/%40keyv/bigmap@1.3.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40keyv/bigmap@1.3.1
Demonstrate these symbols/APIs:
  - createKeyv

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:3133b00779a3db4bfd3038d0677c12bca00a266120c3dbc4eb7f7c79cb076da8","contract":["createKeyv returns a Keyv instance backed by a BigMap store with default or custom storeSize","createKeyv instance supports asynchronous get, set, has, and delete operations","createKeyv instance supports TTL expiration for stored values","createKeyv instance removes all stored keys when clear is called","createKeyv passes custom storeHashFunction to the underlying BigMap adapter for key distribution"],"goal":"verify pkg:npm/%40keyv/bigmap@1.3.1","kind":"HOW","packages":["pkg:npm/%40keyv/bigmap@1.3.1"],"schemaVersion":1,"symbols":["createKeyv"]},"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/%40keyv/bigmap@1.3.1"],"schemaVersion":1,"subject":"pkg:npm/%40keyv/bigmap@1.3.1","symbols":["createKeyv"],"verifierAdapter":"node-typescript@1"}

import { createKeyv, BigMap } from '@keyv/bigmap';

/**
 * Creates a Keyv instance backed by a BigMap store.
 *
 * @param {object} [options] - Configuration options for BigMap adapter
 * @param {number} [options.storeSize] - Number of internal Map instances
 * @param {function} [options.storeHashFunction] - Custom key hash function
 * @returns {import('keyv').Keyv}
 */
export function initKeyvStore(options) {
  return createKeyv(options);
}

export { createKeyv, BigMap };

{
  "name": "sample-keyv-bigmap-createkeyv",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-keyv-bigmap-createkeyv",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@keyv/bigmap": "1.3.1"
      }
    },
    "node_modules/@keyv/bigmap": {
      "version": "1.3.1",
      "resolved": "https://registry.npmjs.org/@keyv/bigmap/-/bigmap-1.3.1.tgz",
      "integrity": "sha512-WbzE9sdmQtKy8vrNPa9BRnwZh5UF4s1KTmSK0KUVLo3eff5BlQNNWDnFOouNpKfPKDnms9xynJjsMYjMaT/aFQ==",
      "license": "MIT",
      "dependencies": {
        "hashery": "^1.4.0",
        "hookified": "^1.15.0"
      },
      "engines": {
        "node": ">= 18"
      },
      "peerDependencies": {
        "keyv": "^5.6.0"
      }
    },
    "node_modules/@keyv/serialize": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/@keyv/serialize/-/serialize-1.1.1.tgz",
      "integrity": "sha512-dXn3FZhPv0US+7dtJsIi2R+c7qWYiReoEh5zUntWCf4oSpMNib8FDhSoed6m3QyZdx5hK7iLFkYk3rNxwt8vTA==",
      "license": "MIT",
      "peer": true
    },
    "node_modules/hashery": {
      "version": "1.5.1",
      "resolved": "https://registry.npmjs.org/hashery/-/hashery-1.5.1.tgz",
      "integrity": "sha512-iZyKG96/JwPz1N55vj2Ie2vXbhu440zfUfJvSwEqEbeLluk7NnapfGqa7LH0mOsnDxTF85Mx8/dyR6HfqcbmbQ==",
      "license": "MIT",
      "dependencies": {
        "hookified": "^1.15.0"
      },
      "engines": {
        "node": ">=20"
      }
    },
    "node_modules/hookified": {
      "version": "1.15.1",
      "resolved": "https://registry.npmjs.org/hookified/-/hookified-1.15.1.tgz",
      "integrity": "sha512-MvG/clsADq1GPM2KGo2nyfaWVyn9naPiXrqIe4jYjXNZQt238kWyOGrsyc/DmRAQ+Re6yeo6yX/yoNCG5KAEVg==",
      "license": "MIT"
    },
    "node_modules/keyv": {
      "version": "5.6.0",
      "resolved": "https://registry.npmjs.org/keyv/-/keyv-5.6.0.tgz",
      "integrity": "sha512-CYDD3SOtsHtyXeEORYRx2qBtpDJFjRTGXUtmNEMGyzYOKj1TE3tycdlho7kA1Ufx9OYWZzg52QFBGALTirzDSw==",
      "license": "MIT",
      "peer": true,
      "dependencies": {
        "@keyv/serialize": "^1.1.1"
      }
    }
  }
}

{
  "name": "sample-keyv-bigmap-createkeyv",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@keyv/bigmap": "1.3.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40keyv/bigmap@1.3.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40keyv/bigmap@1.3.1"
  ],
  "symbols": [
    "createKeyv"
  ]
}

import assert from 'node:assert/strict';
import { createKeyv, BigMap } from '@keyv/bigmap';
import { Keyv } from 'keyv';
import { initKeyvStore } from '../index.mjs';

// 1. createKeyv returns a Keyv instance backed by a BigMap store with default or custom storeSize
{
  const defaultKeyv = createKeyv();
  assert.ok(defaultKeyv instanceof Keyv, 'createKeyv should return a Keyv instance');
  assert.ok(defaultKeyv.opts.store instanceof BigMap, 'Keyv store should be a BigMap instance');
  assert.equal(defaultKeyv.opts.store.storeSize, 4, 'Default storeSize should be 4');

  const customKeyv = initKeyvStore({ storeSize: 8 });
  assert.ok(customKeyv instanceof Keyv, 'initKeyvStore should return a Keyv instance');
  assert.ok(customKeyv.opts.store instanceof BigMap, 'Keyv store should be a BigMap instance');
  assert.equal(customKeyv.opts.store.storeSize, 8, 'Custom storeSize should be 8');
}

// 2. createKeyv instance supports asynchronous get, set, has, and delete operations
{
  const keyv = createKeyv();
  assert.equal(await keyv.has('alpha'), false, 'Key should not exist initially');
  assert.equal(await keyv.get('alpha'), undefined, 'get should return undefined for nonexistent key');

  await keyv.set('alpha', 'value1');
  assert.equal(await keyv.has('alpha'), true, 'has should return true after set');
  assert.equal(await keyv.get('alpha'), 'value1', 'get should return stored value');

  const deleted = await keyv.delete('alpha');
  assert.equal(deleted, true, 'delete should return true for existing key');
  assert.equal(await keyv.has('alpha'), false, 'has should return false after delete');
  assert.equal(await keyv.get('alpha'), undefined, 'get should return undefined after delete');

  const deletedAgain = await keyv.delete('alpha');
  assert.equal(deletedAgain, false, 'delete should return false for nonexistent key');
}

// 3. createKeyv instance supports TTL expiration for stored values
{
  const keyv = createKeyv();
  await keyv.set('tempKey', 'tempValue', 50);
  assert.equal(await keyv.has('tempKey'), true, 'Key should exist before TTL expires');
  assert.equal(await keyv.get('tempKey'), 'tempValue', 'get should return value before TTL expires');

  await new Promise((resolve) => setTimeout(resolve, 80));
  assert.equal(await keyv.get('tempKey'), undefined, 'get should return undefined after TTL expires');
  assert.equal(await keyv.has('tempKey'), false, 'has should return false after TTL expires');
}

// 4. createKeyv instance removes all stored keys when clear is called
{
  const keyv = createKeyv();
  await keyv.set('k1', 'v1');
  await keyv.set('k2', 'v2');
  assert.equal(await keyv.has('k1'), true);
  assert.equal(await keyv.has('k2'), true);

  await keyv.clear();
  assert.equal(await keyv.has('k1'), false, 'k1 should not exist after clear');
  assert.equal(await keyv.has('k2'), false, 'k2 should not exist after clear');
  assert.equal(await keyv.get('k1'), undefined);
  assert.equal(await keyv.get('k2'), undefined);
}

// 5. createKeyv passes custom storeHashFunction to the underlying BigMap adapter for key distribution
{
  let hashCalled = false;
  const customHash = (key, storeSize) => {
    hashCalled = true;
    return 2;
  };

  const keyv = createKeyv({
    storeSize: 6,
    storeHashFunction: customHash,
  });

  await keyv.set('routedKey', 'routedValue');
  assert.equal(hashCalled, true, 'Custom storeHashFunction should be invoked on set');
  assert.equal(await keyv.get('routedKey'), 'routedValue', 'Value should be retrieved through custom hash');
  assert.equal(keyv.opts.store.getStoreMap(2).size, 1, 'Entry should be routed to store index 2');
}

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