@renatorodrigues/cacheiro-types

Shared TypeScript interfaces for the cacheiro ecosystem.

CacheiroStore

Contract every store implementation must satisfy:

export interface CacheiroStore {
  mount(): Promise<void>;
  unmount?(): void;
  exists(hash: string): Promise<boolean>;
  write(hash: string, data: Buffer): Promise<void>;
  read(hash: string): ExpiringReadable;
}

| Method | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | mount() | Called on server startup. Create directories, start timers, etc. | | unmount() | Optional. Called on server shutdown. Stop timers, flush buffers, etc. | | exists() | Returns true if artifact exists (regardless of expiry — lazy expiry is checked in read()). | | write() | Persist artifact data for the given hash. | | read() | Return an ExpiringReadable for the artifact — see ExpiringReadable below. Signal not-found via a stream 'error' event, not a synchronous throw. |

ExpiringReadable

A Readable stream with an optional .expired flag, returned by CacheiroStore.read():

import type { Readable } from 'node:stream';

export interface ExpiringReadable extends Readable {
  expired?: boolean;
}

Set .expired = true when the artifact being served is past its TTL and is being returned one last time before removal — see cacheiro-store-fs for TTL behavior. Since expired is optional, a plain Readable satisfies this interface — stores without TTL support (e.g. cacheiro-store-s3/gcs/azure) can just return a regular stream.

Describable

Optional interface for stores that want to expose config info to the startup banner:

export interface Describable {
  describe(): [string, string][];
}

Returns a list of [label, value] rows displayed in the banner info box. The banner duck-types 'describe' in store — implementing this interface is optional.

Available stores

| Package | Description | | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | cacheiro-store-fs | Local filesystem | | cacheiro-store-s3 | AWS S3 and S3-compatible storage (MinIO, LocalStack, etc.) | | cacheiro-store-gcs | Google Cloud Storage | | cacheiro-store-azure | Azure Blob Storage |

Adding a custom store

Implement the CacheiroStore interface:

import type { CacheiroStore, ExpiringReadable } from '@renatorodrigues/cacheiro-types';

export class MyStore implements CacheiroStore {
  async mount(): Promise<void> { ... }
  async exists(hash: string): Promise<boolean> { ... }
  async write(hash: string, data: Buffer): Promise<void> { ... }
  read(hash: string): ExpiringReadable { ... }
}

See cacheiro-store-fs as a reference implementation.

Development

npm run watch        # tsc --watch (hot rebuild)
npm run build        # compile TypeScript