npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@openknot-ts/cache

v0.0.6-preview

Published

OpenKnot's cache primitive: read-through, write-through and snapshot layers over consumer-owned native stores, coherent with Units of Work.

Readme

@openknot-ts/cache

Cache layers for readers. A module lists cache({ ... }) beside the reader plug; it wraps the readers through decorate(), and with several layers the first listed is closest to the source. The application keeps its own store, with its storage, TTL and capacity.

Usage

export const roleCache = cache({
  entity: "role",
  strategy: "write-through",
  requirements: { localRoles },
  port: reader.compose({ byId: findRole }),
  writers: saveRole,
  persist:
    ({ localRoles }) =>
    (changes) =>
      applyTo(localRoles, changes),
  bind: ({ localRoles }) => ({ byId: (id) => localRoles.get(id) }),
});

export const roleReaders = plug({ port: roleReaderPorts, requirements: { database }, bind });

export const io = providePlugs([roleReaders, roleCache]);

API

cache({ entity, strategy?, name?, requirements?, port, persist, bind, connection?, writers?, include?, load?, startup?, order? })

| Option | Description | | --- | --- | | entity | The entity literal of the port's states, checked by TypeScript. | | persist | Applies set/delete/clear changes; calls must take effect in order. | | bind | Reads the store per member: a value, undefined for a miss, or completed/empty/unsupported. | | strategy | See below; read-through by default. | | writers | Writers whose receipts write-through inserts. | | include | Which states the layer keeps; a failing state is removed. | | load, startup | Snapshot loading. | | order | Projection for newer-wins; the state's version by default. | | connection | A ConnectionWatch reporting the store's state. |

The package also exports completed, empty, unsupported and cacheKey. The layer's health check reports failures as down when listed in a module.

Strategies

| Strategy | Fills | Commits | Lists | | --- | --- | --- | --- | | read-through | On a miss, once a lower layer answers; inside a Unit of Work after commit, skipped if it wrote the entity | upserts set, deletes delete | next layer | | write-through | From the committed receipts of writers | other upserts and deletes evict | next layer | | snapshot | At startup through load: a reader loads a complete set, a function a partial one | upserts set, deletes delete | from the store when complete |

A snapshot with include is partial. startup: "blocking" waits for the load; with "background" reads go to the source until it completes. Large loads may return pages as an async iterable.

Commits and reads

  • Committed changes reach every layer after commit hooks and before effects and publications. The command waits for each available layer's persist until its store is reported lost. An afterCommit hook of unitOfWork({ hooks }) still reads the old state; an effect from ctx.uow.afterCommit reads the new one.
  • undefined is the only miss; null is a hit, so map nil answers to undefined: byId: async (id) => (await client.get(id)) ?? undefined. completed(undefined) answers known absence. Empty source answers fill nothing.
  • Newer changes win by order. While writes or fills are in flight the layer keeps the newest order, so a late write cannot overwrite a newer state or revive a deleted one. Entities without an order are evicted on commit.
  • Inside a Unit of Work, a cached result containing an entity it wrote is read from the source; a complete snapshot sends lists and absence to the source once it wrote that entity.

Single-flight

  • Concurrent misses of the same member and arguments share one source read. Reads inside a Unit of Work share only within it, and stop sharing once it writes the entity.
  • A committed change retires outside flights of every layer of that entity, so a read after the command returns starts fresh.
  • A follower whose leader fails, or whose shared result contains an entity its Unit of Work wrote, reads the source itself.

Result keys

Ports that return other results cache them by cacheKey(...args), without entity and without following commits. cacheKey encodes undefined, null, booleans, numbers, bigints, strings, valid dates, arrays and plain objects (property order ignored, -0 distinct from 0), and returns undefined for anything else, which bypasses caching.

Availability

  • A failing store makes the layer unavailable: reads continue below and commands do not fail. Failures become spans with tracing.
  • After lost, the layer makes no store calls and ends every wait on the store; commands and stop finish behind a lost store.
  • restored starts a recovery, which clears the store through persist and reloads a snapshot. Until it ends, reads go to the source and health is down.
  • Without a connection, a failed call makes the layer unavailable and the next read or commit recovers.
  • Background work (recovery and its reads) keeps the startup context; start the application outside any transaction.

Snapshot placement

A complete snapshot needs a per-instance store: a recovery on another instance sharing it would clear it. @openknot-ts/replication is the shared form. Entities without an order belong on read-through; on a snapshot a commit evicts the row until the next reload.

Example

pnpm --filter @openknot-ts/cache example runs examples/memory.ts, a write-through cache over a Map.