@cacheable/utils 2.5.0: CacheTags

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/%40cacheable/utils@2.5.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/%40cacheable/utils@2.5.0
Demonstrate these symbols/APIs:
  - CacheTags

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:ab181009fbca8079d1f24241f267941cd346206b18195cc166e2d4e331fbdc4f","contract":["CacheTags initializes with backing store, namespace, and enabled state toggled via property setter","CacheTags setKeyTags associates a cache key with tag version snapshots and deduplicates input tags","CacheTags isKeyFresh returns true for tagged keys with current versions and false for untagged keys","CacheTags invalidateTag bumps tag version counter rendering referencing keys stale immediately","CacheTags invalidateTags bumps multiple tag version counters in a single batch operation","CacheTags isKeyStale returns true only when key snapshot exists and at least one tag is invalidated","CacheTags getStaleKeys identifies stale keys from a list using batched store reads","CacheTags getTags returns associated tags for a key or undefined for untagged keys","CacheTags removeKey and removeKeys delete tag snapshots and reset key freshness","CacheTags getKeysByTag returns all cache keys referencing the specified tag","CacheTags skips operations and returns neutral values when disabled"],"goal":"verify pkg:npm/%40cacheable/utils@2.5.0","kind":"HOW","packages":["pkg:npm/%40cacheable/utils@2.5.0"],"schemaVersion":1,"symbols":["CacheTags"]},"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/%40cacheable/utils@2.5.0"],"schemaVersion":1,"subject":"pkg:npm/%40cacheable/utils@2.5.0","symbols":["CacheTags"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-cacheable-utils-cache-tags",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-cacheable-utils-cache-tags",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "@cacheable/utils": "2.5.0"
      }
    },
    "node_modules/@cacheable/utils": {
      "version": "2.5.0",
      "resolved": "https://registry.npmjs.org/@cacheable/utils/-/utils-2.5.0.tgz",
      "integrity": "sha512-buipgOVDkkPXNR5+xBpDw7Zk2n1EvU7qBJCNUcL7rhQ//kfpOXPAvQ511Os0vpLYJ1pZnvudNytkQt2hst3wqA==",
      "license": "MIT",
      "dependencies": {
        "hashery": "^1.5.1",
        "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"
    },
    "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",
      "dependencies": {
        "@keyv/serialize": "^1.1.1"
      }
    }
  }
}

{
  "name": "sample-cacheable-utils-cache-tags",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "@cacheable/utils": "2.5.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/%40cacheable/utils@2.5.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/%40cacheable/utils@2.5.0"
  ],
  "symbols": [
    "CacheTags"
  ]
}

import { CacheTags } from '@cacheable/utils';
import { Keyv } from 'keyv';

/**
 * Creates and initializes a CacheTags service instance.
 * @param {import('@cacheable/utils').CacheTagsOptions} [options]
 * @returns {CacheTags}
 */
export function createCacheTags(options = {}) {
  const store = options.store ?? new Keyv();
  return new CacheTags({ ...options, store });
}

export { CacheTags };
export default CacheTags;

import assert from 'node:assert/strict';
import { CacheTags } from '@cacheable/utils';
import { Keyv } from 'keyv';
import { createCacheTags } from '../src/index.mjs';

// 1. CacheTags initializes with backing store, namespace, and enabled state toggled via property setter
{
  const store = new Keyv();
  const cacheTags = new CacheTags({ store, namespace: 'custom-ns' });
  assert.equal(cacheTags.store, store);
  assert.equal(cacheTags.namespace, 'custom-ns');
  assert.equal(cacheTags.enabled, true);

  cacheTags.enabled = false;
  assert.equal(cacheTags.enabled, false);

  cacheTags.enabled = true;
  assert.equal(cacheTags.enabled, true);

  const defaultService = createCacheTags();
  assert.equal(defaultService.namespace, 'default');
  assert.equal(defaultService.enabled, true);
}

// 2. CacheTags setKeyTags associates a cache key with tag version snapshots and deduplicates input tags
{
  const cacheTags = createCacheTags();
  await cacheTags.setKeyTags('article:1', ['news', 'tech', 'news', 'tech']);
  const tags = await cacheTags.getTags('article:1');
  assert.deepEqual(tags, ['news', 'tech']);
}

// 3. CacheTags isKeyFresh returns true for tagged keys with current versions and false for untagged keys
{
  const cacheTags = createCacheTags();
  assert.equal(await cacheTags.isKeyFresh('untagged-key'), false);

  await cacheTags.setKeyTags('article:fresh', ['news']);
  assert.equal(await cacheTags.isKeyFresh('article:fresh'), true);

  await cacheTags.setKeyTags('empty-tagged', []);
  assert.equal(await cacheTags.isKeyFresh('empty-tagged'), true);
}

// 4. CacheTags invalidateTag bumps tag version counter rendering referencing keys stale immediately
{
  const cacheTags = createCacheTags();
  await cacheTags.setKeyTags('doc:1', ['shared-tag', 'doc-only']);
  await cacheTags.setKeyTags('doc:2', ['other-tag']);

  assert.equal(await cacheTags.isKeyFresh('doc:1'), true);
  assert.equal(await cacheTags.isKeyFresh('doc:2'), true);

  const invalidated = await cacheTags.invalidateTag('shared-tag');
  assert.deepEqual(invalidated, ['shared-tag']);

  assert.equal(await cacheTags.isKeyFresh('doc:1'), false);
  assert.equal(await cacheTags.isKeyFresh('doc:2'), true);
}

// 5. CacheTags invalidateTags bumps multiple tag version counters in a single batch operation
{
  const cacheTags = createCacheTags();
  await cacheTags.setKeyTags('item:a', ['tag-a']);
  await cacheTags.setKeyTags('item:b', ['tag-b']);
  await cacheTags.setKeyTags('item:c', ['tag-c']);

  const invalidated = await cacheTags.invalidateTags(['tag-a', 'tag-b', 'tag-a']);
  assert.deepEqual(invalidated, ['tag-a', 'tag-b', 'tag-a']);

  assert.equal(await cacheTags.isKeyFresh('item:a'), false);
  assert.equal(await cacheTags.isKeyFresh('item:b'), false);
  assert.equal(await cacheTags.isKeyFresh('item:c'), true);
}

// 6. CacheTags isKeyStale returns true only when key snapshot exists and at least one tag is invalidated
{
  const cacheTags = createCacheTags();
  assert.equal(await cacheTags.isKeyStale('non-existent'), false);

  await cacheTags.setKeyTags('item:active', ['valid-tag']);
  assert.equal(await cacheTags.isKeyStale('item:active'), false);

  await cacheTags.invalidateTag('valid-tag');
  assert.equal(await cacheTags.isKeyStale('item:active'), true);
}

// 7. CacheTags getStaleKeys identifies stale keys from a list using batched store reads
{
  const cacheTags = createCacheTags();
  await cacheTags.setKeyTags('k1', ['group1']);
  await cacheTags.setKeyTags('k2', ['group2']);
  await cacheTags.setKeyTags('k3', ['group1', 'group2']);

  await cacheTags.invalidateTag('group1');

  const stale = await cacheTags.getStaleKeys(['k1', 'k2', 'k3', 'untagged']);
  assert.deepEqual(stale, ['k1', 'k3']);
}

// 8. CacheTags getTags returns associated tags for a key or undefined for untagged keys
{
  const cacheTags = createCacheTags();
  assert.equal(await cacheTags.getTags('missing-key'), undefined);

  await cacheTags.setKeyTags('post:42', ['blog', 'release']);
  const tags = await cacheTags.getTags('post:42');
  assert.deepEqual(tags, ['blog', 'release']);
}

// 9. CacheTags removeKey and removeKeys delete tag snapshots and reset key freshness
{
  const cacheTags = createCacheTags();
  await cacheTags.setKeyTags('single:1', ['t1']);
  await cacheTags.setKeyTags('multi:1', ['t2']);
  await cacheTags.setKeyTags('multi:2', ['t3']);

  assert.equal(await cacheTags.isKeyFresh('single:1'), true);
  await cacheTags.removeKey('single:1');
  assert.equal(await cacheTags.isKeyFresh('single:1'), false);
  assert.equal(await cacheTags.getTags('single:1'), undefined);

  assert.equal(await cacheTags.isKeyFresh('multi:1'), true);
  assert.equal(await cacheTags.isKeyFresh('multi:2'), true);
  await cacheTags.removeKeys(['multi:1', 'multi:2']);
  assert.equal(await cacheTags.isKeyFresh('multi:1'), false);
  assert.equal(await cacheTags.isKeyFresh('multi:2'), false);
  assert.equal(await cacheTags.getTags('multi:1'), undefined);
  assert.equal(await cacheTags.getTags('multi:2'), undefined);
}

// 10. CacheTags getKeysByTag returns all cache keys referencing the specified tag
{
  const cacheTags = createCacheTags();
  await cacheTags.setKeyTags('entity:1', ['common', 'type:a']);
  await cacheTags.setKeyTags('entity:2', ['common', 'type:b']);
  await cacheTags.setKeyTags('entity:3', ['type:b']);

  const commonKeys = await cacheTags.getKeysByTag('common');
  assert.deepEqual(commonKeys.sort(), ['entity:1', 'entity:2']);

  const typeBKeys = await cacheTags.getKeysByTag('type:b');
  assert.deepEqual(typeBKeys.sort(), ['entity:2', 'entity:3']);

  const unknownKeys = await cacheTags.getKeysByTag('nonexistent');
  assert.deepEqual(unknownKeys, []);
}

// 11. CacheTags skips operations and returns neutral values when disabled
{
  const cacheTags = createCacheTags({ enabled: false });
  assert.equal(cacheTags.enabled, false);

  await cacheTags.setKeyTags('ignored:key', ['some-tag']);
  assert.equal(await cacheTags.isKeyFresh('ignored:key'), true);
  assert.equal(await cacheTags.isKeyStale('ignored:key'), false);
  assert.equal(await cacheTags.getTags('ignored:key'), undefined);
  assert.deepEqual(await cacheTags.getStaleKeys(['ignored:key']), []);
  assert.deepEqual(await cacheTags.invalidateTag('some-tag'), []);
  assert.deepEqual(await cacheTags.invalidateTags(['some-tag']), []);
  assert.deepEqual(await cacheTags.getKeysByTag('some-tag'), []);
}

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