Migrations

Upgrade guides for breaking changes to the cachetta npm package. Each entry is required to include all five sections below. Write “None.” if a section truly has no content, so reviewers know it was considered.

v0.3 → v0.4

Summary

The implicit “sibling-hash” behavior has been removed. When path was a string, cachetta used to silently rewrite the filename into a {name}-{hash}{ext} sibling whenever the wrapped function received arguments. That default collided across functions that happened to share a base name in the same folder, left a dead name prefix on every file, and gave callers no clean way to organize multiple cache kinds under one root. A string path now means exactly that: cachetta writes to the literal path you gave it, regardless of arguments.

Required changes

| Before | After | |——–|——-| | new Cachetta({ path: 'cache/llm.json' })
wrapped fn(prompt) → cache/llm-<hash>.json | new Cachetta({ path: (prompt) => cache/llm/${prompt}.json })
explicit per-arg path function | | const cache = new Cachetta({ path: 'cache.json' })
await cache.invalidate('a')
removed cache-<hash>.json | const cache = new Cachetta({ path: (x) => cache/${x}.json })
await cache.invalidate('a')
removes the path you actually wrote |

If a single literal file is what you actually want, no change is needed — that’s the new default.

Deprecations removed

• The implicit {name}-{hash}{ext} sibling rewrite in Cachetta._getPath when path is a string.

Behavior changes without code changes

• new Cachetta({ path: 'cache.json' }) wrapping a function with arguments now writes every call to cache.json (last write wins) instead of fanning out into per-args sibling files. Existing on-disk cache-<hash>.json files written by older versions are no longer read; delete or migrate them by hand if you need their contents.

Verification

• After upgrading, run:

  import { Cachetta } from 'cachetta';
  const cache = new Cachetta({ path: '/tmp/cachetta_check.json' });
  console.assert(cache._getPath('anything') === '/tmp/cachetta_check.json');
  

  The assertion should hold; pre-upgrade it produced a path of the form /tmp/cachetta_check-<hash>.json.