@zerotal/cache 1.6.3 → 1.7.2

package/api-surface.md

@@ -0,0 +1,188 @@
+# @zerotal/cache — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class CacheDeserializationError = {
+  new (key: string, cause: unknown): CacheDeserializationError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class CacheError = {
+  new (message: string, code?: string, status?: number, context?: Record<string, unknown>): CacheError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class CacheEvicted = {
+  new (key: string, reason: 'ttl' | 'capacity' | 'manual'): CacheEvicted
+  readonly key: string
+  readonly reason: 'ttl' | 'capacity' | 'manual'
+}
+
+class CacheManager = {
+  new (_driver: CacheDriver, _prefix?: string, _defaultTtl?: number | undefined, _lock?: LockManager | null, _stampedeProtection?: boolean): CacheManager
+  dispose: () => void
+  flush: () => Promise<void>
+  forever: (key: string, value: unknown) => Promise<void>
+  forget: (key: string) => Promise<void>
+  get: <T>(key: string) => Promise<T | null>
+  has: (key: string) => Promise<boolean>
+  remember: <T>(key: string, ttl: number, fn: () => Promise<T> | T) => Promise<T>
+  set: (key: string, value: unknown, ttl?: number) => Promise<void>
+  tags: (tagNames: string[]) => TaggedCache
+}
+
+class CacheProvider = {
+  new (app: Application): CacheProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static priority?: number
+  static provides: readonly ['cache']
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class CacheQueried = {
+  new (op: 'hit' | 'miss' | 'write' | 'forget' | 'flush' | 'has', key: string, ttl: number | undefined, durationMs: number): CacheQueried
+  readonly durationMs: number
+  readonly key: string
+  readonly op: 'hit' | 'miss' | 'write' | 'forget' | 'flush' | 'has'
+  readonly ttl: number | undefined
+}
+
+class CacheSerializationError = {
+  new (key: string, cause: unknown): CacheSerializationError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class IdempotencyMiddleware = {
+  new (): IdempotencyMiddleware
+  static _clearInFlight: () => void
+  static with: <T extends new (...args: any[]) => BaseMiddleware<any>, Opts = T extends new (...args: any[]) => BaseMiddleware<infer U> ? U : object>(this: T, options: DeepPartial<NoInfer<Opts>>) => new () => InstanceType<T>
+  afterResponse?: (ctx: HttpContext) => Promise<void>
+  handle: (http: HttpContext, next: NextFn) => Promise<Response | void>
+  onError?: (ctx: HttpContext, error: Error) => Promise<void>
+}
+
+class MemoryDriver = {
+  new (sweepMs?: number): MemoryDriver
+  dispose: () => void
+  flush: (prefix?: string) => Promise<void>
+  forget: (key: string) => Promise<void>
+  get: (key: string) => Promise<string | null>
+  has: (key: string) => Promise<boolean>
+  set: (key: string, value: string, ttl?: number) => Promise<void>
+  size: number
+  sweep: () => void
+}
+
+class RedisDriver = {
+  new (prefix?: string): RedisDriver
+  flush: (prefix?: string) => Promise<void>
+  forget: (key: string) => Promise<void>
+  get: (key: string) => Promise<string | null>
+  has: (key: string) => Promise<boolean>
+  set: (key: string, value: string, ttl?: number) => Promise<void>
+}
+
+class SqliteDriver = {
+  new (sqlInstance: SqlConnection): SqliteDriver
+  flush: (prefix?: string) => Promise<void>
+  forget: (key: string) => Promise<void>
+  get: (key: string) => Promise<string | null>
+  has: (key: string) => Promise<boolean>
+  set: (key: string, value: string, ttl?: number) => Promise<void>
+}
+
+class TaggedCache = {
+  new (_driver: CacheDriver, _prefix?: string, _defaultTtl?: number | undefined, _lock?: LockManager | null, _stampedeProtection?: boolean): TaggedCache
+  dispose: () => void
+  flush: () => Promise<void>
+  forever: (key: string, value: unknown) => Promise<void>
+  forget: (key: string) => Promise<void>
+  get: <T>(key: string) => Promise<T | null>
+  has: (key: string) => Promise<boolean>
+  remember: <T>(key: string, ttl: number, fn: () => Promise<T> | T) => Promise<T>
+  set: (key: string, value: unknown, ttl?: number) => Promise<void>
+  tags: (tagNames: string[]) => TaggedCache
+}
+
+const Cache = CacheManager
+
+function CacheConfig = (options?: Partial<CacheConfigShape>) => CacheConfigShape
+
+interface CacheConfigShape = {
+  driver: 'sqlite' | 'redis' | 'memory'
+  prefix: string
+  sqlite: {    path: string;}
+  stampedeProtection: boolean
+  ttl: number
+}
+
+interface CacheDriver = {
+  dispose?: () => void
+  flush: (prefix?: string) => Promise<void>
+  forget: (key: string) => Promise<void>
+  get: (key: string) => Promise<string | null>
+  has: (key: string) => Promise<boolean>
+  set: (key: string, value: string, ttl?: number) => Promise<void>
+}
+
+interface IdempotencyOptions = {
+  cache: CacheManager | undefined
+  header: string
+  lock?: LockManager
+  methods: string[]
+  ttl: number
+  useLock: boolean
+  validateBody: boolean
+}
+
+## ./commands  `(./src/commands/index.ts)`
+
+class CacheClearCommand = {
+  new (): CacheClearCommand
+  static args: ArgDef[]
+  static commandName: string
+  static description: string
+  static flags: {    name: string;    type: 'string';    description: string;}[]
+  static needsApp: boolean
+  _readLine: () => Promise<string>
+  _writer: OutputWriter
+  app: unknown
+  args: Record<string, string>
+  ask: (question: string, defaultValue?: string) => Promise<string>
+  choice: (question: string, options: string[]) => Promise<string>
+  confirm: (question: string, defaultValue?: boolean) => Promise<boolean>
+  dim: (msg: string) => void
+  error: (msg: string) => void
+  flags: Record<string, string | number | boolean>
+  info: (msg: string) => void
+  line: (msg: string) => void
+  newLine: () => void
+  run: () => Promise<void>
+  secret: (question: string) => Promise<string>
+  section: (title: string) => void
+  table: (rows: [string, string][], indent?: number) => void
+  warn: (msg: string) => void
+  write: (msg: string) => void
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/cache",
-  "version": "1.6.3",
+  "version": "1.7.2",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -13,6 +13,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -30,7 +31,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.3"
+    "@zerotal/core": "1.7.2"
   },
   "devDependencies": {
     "typescript": "^5.8.0"