@orieljs/framework 0.1.0-alpha.6 → 0.1.0-alpha.8

package/docs/cache.md

@@ -0,0 +1,647 @@
+# Cache
+
+Keep the result of slow work, such as a heavy query or a call to another service, in the cache, and read it back
+quickly on the next request.
+
+## Introduction
+
+Some of the data your app reads or computes takes a while to get, and stays the same for a time. Store it in a cache
+and later requests read it from there. Oriel's cache has one API over several stores: your database, files, Redis, or
+your app's memory.
+
+## Configuration
+
+The cache's settings are in `config/cache.ts`. `default` names the store that the `Cache` facade uses, and a new app
+uses the `database` store:
+
+```ts title="config/cache.ts"
+import { dirname, join } from 'node:path'
+import { env, Str } from '@orieljs/framework'
+
+const basePath = dirname(import.meta.dirname)
+
+export default {
+  default: env('CACHE_STORE', 'database'),
+  stores: {
+    array: { driver: 'array' },
+    database: { driver: 'database', table: 'cache', lockTable: 'cache_locks' },
+    file: { driver: 'file', path: join(basePath, 'storage/framework/cache/data') },
+    redis: { driver: 'redis', connection: 'cache' },
+  },
+  prefix: env('CACHE_PREFIX', Str.slug(String(env('APP_NAME', 'oriel')), '_') + '_cache_'),
+}
+```
+
+Each store has a driver:
+
+- `database`: in the `cache` table of your database.
+- `file`: one file per key, in `storage/framework/cache/data`.
+- `redis`: in Redis.
+- `array`: in memory, in your app's process. Your tests use it.
+- `memory`: in memory too, with an optional `maxItems`: past that number of entries, the least recently used one is
+  dropped. A new app's config doesn't list a `memory` store; add one to use it:
+  `memory: { driver: 'memory', maxItems: 1000 }`.
+
+`prefix` starts every key, so that two apps can share a store: `blog_cache_` for an app called Blog. A store can set
+its own `prefix`.
+
+> [!NOTE]
+> Laravel's `array` store is empty at the start of each request. Oriel's process outlives each request, so an `array`
+> or `memory` store keeps its entries for as long as the process runs, and loses them when it restarts. Each process
+> has its own: two servers, or a server and a queue worker, don't share them.
+
+### Driver prerequisites
+
+#### Database
+
+The `database` store needs the `cache` table, and its locks the `cache_locks` table. A new app's
+`0001_01_01_000001_create_cache_table.ts` migration creates both:
+
+```ts
+await Schema.create('cache', (t) => {
+  t.string('key').primary()
+  t.text('value')
+  t.integer('expiration')
+})
+await Schema.create('cache_locks', (t) => {
+  t.string('key').primary()
+  t.string('owner')
+  t.integer('expiration')
+})
+```
+
+A store's `connection` names the database connection to use, the default one when it has none, and `table` and
+`lockTable` the tables.
+
+#### Redis
+
+The `redis` store talks to the Redis server of `config/database.ts`: `connection` names an entry of `database.redis`.
+A new app's `cache` entry is its own Redis database, number 1 unless you set `REDIS_CACHE_DB`, so that flushing the
+cache leaves your sessions and queued jobs alone. Oriel's Redis client, `ioredis`, comes with the framework, and the
+connection is closed when your app shuts down.
+
+## Cache usage
+
+### Obtaining a cache instance
+
+The `Cache` facade reaches the default store. Every method is async, so `await` it:
+
+```ts title="app/Http/Controllers/UserController.ts"
+import { Cache } from '@orieljs/framework'
+import { Controller } from './Controller'
+
+export class UserController extends Controller {
+  /** Show a list of all users of the application. */
+  async index() {
+    const value = await Cache.get('key')
+
+    return { value }
+  }
+}
+```
+
+#### Accessing multiple cache stores
+
+`Cache.store()` returns another store of `config/cache.ts` by its name:
+
+```ts
+const value = await Cache.store('file').get('foo')
+
+await Cache.store('redis').put('bar', 'baz', 600) // 10 Minutes
+```
+
+A name that isn't in `stores` is an error: "Cache store [mongo] is not configured. Add it to config('cache.stores').".
+
+### Retrieving items from the cache
+
+`get()` returns the value of a key, or `undefined` when the cache has no such key. A second argument is the default,
+returned in its place:
+
+```ts
+const value = await Cache.get('key')
+
+const valueOrDefault = await Cache.get('key', 'default')
+```
+
+The default may be a function, which is only called when the key is missing, so a costly default isn't computed for
+nothing:
+
+```ts
+const users = await Cache.get('users', () => DB.table('users').get())
+```
+
+`get()` takes a type for the value, which is a cast, not a check: `Cache.get<string>('name')`.
+
+`many()` reads several keys at once, and returns an object with a value, or `undefined`, for each:
+
+```ts
+const values = await Cache.many(['name', 'email'])
+```
+
+#### Determining item existence
+
+`has()` tells you whether a key is in the cache, and `missing()` whether it isn't. A key stored with a `null` value
+is in the cache:
+
+```ts
+if (await Cache.has('key')) {
+  // ...
+}
+```
+
+> [!NOTE]
+> Laravel's `has()` is `false` for a key whose value is `null`, because `null` is how Laravel reports a miss. Oriel
+> reports a miss as `undefined`, so a stored `null` is a value like any other.
+
+#### Incrementing / decrementing values
+
+`increment()` and `decrement()` change the number stored under a key, by 1 or by the amount you give, and return the
+new value. A missing key counts as 0, and is then stored with no expiry; a key that has one keeps it:
+
+```ts
+declare const amount: number
+// ---cut---
+// Initialize the value if it does not exist...
+await Cache.add('key', 0, 4 * 60 * 60)
+
+// Increment or decrement the value...
+await Cache.increment('key')
+await Cache.increment('key', amount)
+await Cache.decrement('key')
+await Cache.decrement('key', amount)
+```
+
+#### Retrieve and store
+
+`remember()` returns the value of a key, or, when it is missing, calls your function, stores what it returns for the
+number of seconds you give, and returns that:
+
+```ts
+declare const seconds: number
+// ---cut---
+const users = await Cache.remember('users', seconds, () => DB.table('users').get())
+```
+
+`rememberForever()` does the same, and stores the value with no expiry:
+
+```ts
+const users = await Cache.rememberForever('users', () => DB.table('users').get())
+```
+
+The function may be async. A function that returns `undefined` stores nothing, so it is called again next time.
+
+#### Retrieve and delete
+
+`pull()` returns a value and removes it from the cache. Like `get()`, it returns `undefined`, or the default you give,
+when the key is missing:
+
+```ts
+const value = await Cache.pull('key')
+
+const valueOrDefault = await Cache.pull('key', 'default')
+```
+
+### Storing items in the cache
+
+`put()` stores a value for a number of seconds:
+
+```ts
+await Cache.put('key', 'value', 10)
+```
+
+Without a number of seconds, it stores the value with no expiry:
+
+```ts
+await Cache.put('key', 'value')
+```
+
+Times are always in seconds, and may have a fraction: `Cache.put('key', 'value', 0.5)` keeps the value for half a
+second, though the `database` store rounds it up to whole seconds.
+
+> [!NOTE]
+> Laravel's `put()` also takes a `DateTime` for when the value expires. Oriel's takes seconds only: for a date, pass
+> the seconds until it, `Math.ceil((date.getTime() - Date.now()) / 1000)`.
+
+#### What a value can be
+
+A value is stored as JSON, in every store, the `array` one included, so it comes back the same whichever store you
+use. Store plain data: strings, numbers, booleans, `null`, and arrays and plain objects of those. Anything else comes
+back changed:
+
+- a `Date` comes back as its ISO string, `'2026-01-02T03:04:05.000Z'`; read it with `new Date(value)`;
+- a class instance, a model for one, comes back as a plain object with its fields, without its methods;
+- a `Map` or a `Set` comes back as `{}`;
+- `undefined` as a value is stored as `null`, and `NaN` and `Infinity` as `null`.
+
+To cache a model, cache what you need from it, such as its attributes, and use them as plain data:
+
+```ts
+const post = await Cache.remember('post:1', 60, async () => (await Post.findOrFail(1)).toArray())
+```
+
+#### Store if not present
+
+`add()` stores a value only when the key is missing, and tells you whether it did. It is atomic in every store, so
+two requests that race for the same key can't both add it:
+
+```ts
+declare const seconds: number
+// ---cut---
+const added = await Cache.add('key', 'value', seconds)
+```
+
+#### Storing items forever
+
+`forever()` stores a value with no expiry. Remove it with `forget()`:
+
+```ts
+await Cache.forever('key', 'value')
+```
+
+On the `database` store, "forever" is ten years.
+
+### Removing items from the cache
+
+`forget()` removes a key:
+
+```ts
+await Cache.forget('key')
+```
+
+So does `put()` with zero or a negative number of seconds:
+
+```ts
+await Cache.put('key', 'value', 0)
+
+await Cache.put('key', 'value', -5)
+```
+
+`flush()` removes every key of the store:
+
+```ts
+await Cache.flush()
+```
+
+When the store has a prefix, as a new app's do, `flush()` removes only the keys that start with it, in the `database`
+and `redis` stores. The `file` store deletes its folder, and the `array` store empties itself.
+
+> [!WARNING]
+> A `redis` store with no prefix flushes every key of its Redis database. Give the cache a Redis database of its own,
+> as a new app's `cache` connection does.
+
+### The cache helper
+
+`cache()` reads and writes the default store too. With a key, it returns the key's value. With an object, it stores
+each of its entries, for the number of seconds you give, or with no expiry:
+
+```ts
+declare const seconds: number
+// ---cut---
+const value = await cache('key')
+
+await cache({ key: 'value' }, seconds)
+```
+
+With nothing, it returns the cache, whose methods are the facade's:
+
+```ts
+declare const seconds: number
+// ---cut---
+const users = await cache().remember('users', seconds, () => DB.table('users').get())
+```
+
+> [!NOTE]
+> Laravel's cache also has `flexible()` (stale while revalidate), `memo()`, `putMany()`, `touch()` and a `failover`
+> driver. They aren't in Oriel: write each key with `put()`, and wrap a store's calls yourself to fall back on
+> another.
+
+## Cache tags
+
+Tags group related keys so you can remove them together. Only the `redis` store has them: on any other store,
+`tags()` throws "The [DatabaseStore] cache store does not support tags. Only the redis store does.".
+
+### Storing tagged cache items
+
+`tags()` takes one tag or a list, and returns a cache whose keys belong to those tags:
+
+```ts
+declare const john: object
+declare const anne: object
+declare const seconds: number
+// ---cut---
+await Cache.tags(['people', 'artists']).put('John', john, seconds)
+await Cache.tags(['people', 'authors']).put('Anne', anne, seconds)
+```
+
+### Accessing tagged cache items
+
+A tagged key is read with the same tags it was stored with, in any order:
+
+```ts
+const john = await Cache.tags(['people', 'artists']).get('John')
+
+const anne = await Cache.tags(['people', 'authors']).get('Anne')
+```
+
+### Removing tagged cache items
+
+`flush()` on a tagged cache removes every key stored with any of its tags. This removes both `John` and `Anne`:
+
+```ts
+await Cache.tags(['people', 'authors']).flush()
+```
+
+This removes only `Anne`, the one tagged `authors`:
+
+```ts
+await Cache.tags('authors').flush()
+```
+
+> [!WARNING]
+> Flushing a tag doesn't delete its keys from Redis: it gives the tag a new version, so they can't be read any more,
+> and they stay until they expire. Give tagged keys a number of seconds, or they stay for good.
+
+## Atomic locks
+
+A lock lets one process at a time do a piece of work, across every process and server that shares the store. Every
+store has locks. The `database` store keeps them in the `cache_locks` table, and the `redis` store in Redis; the
+`file` store's work for the processes of one machine, and the `array` store's only within one process.
+
+### Managing locks
+
+`Cache.lock()` takes the lock's name and how many seconds it lasts at most. `get()` tries once to take it, and tells
+you whether it did:
+
+```ts
+const lock = Cache.lock('foo', 10)
+
+if (await lock.get()) {
+  // Lock acquired for 10 seconds...
+
+  await lock.release()
+}
+```
+
+`get()` also takes a function. When the lock is taken, it runs the function, releases the lock, and returns what the
+function returned; when it isn't, it returns `false`:
+
+```ts
+await Cache.lock('foo', 10).get(async () => {
+  // Lock acquired for 10 seconds and automatically released...
+})
+```
+
+`block()` waits for the lock, up to a number of seconds. When the time is up, it throws a `LockTimeoutError`,
+"Unable to acquire lock [foo].":
+
+```ts
+const lock = Cache.lock('foo', 10)
+
+try {
+  await lock.block(5)
+
+  // Lock acquired after waiting a maximum of 5 seconds...
+} catch (error) {
+  if (!(error instanceof LockTimeoutError)) throw error
+
+  // Unable to acquire lock...
+} finally {
+  await lock.release()
+}
+```
+
+Given a function, `block()` runs it once the lock is taken, and releases the lock after:
+
+```ts
+await Cache.lock('foo', 10).block(5, async () => {
+  // Lock acquired for 10 seconds after waiting a maximum of 5 seconds...
+})
+```
+
+A lock without a number of seconds lasts until it is released. `release()` releases a lock only for its owner, the
+lock object that took it, and returns whether it did.
+
+> [!NOTE]
+> On every store but `database`, a lock is a key of the cache: `Cache.lock('foo')` and `Cache.put('foo', …)` name the
+> same entry, as in Laravel. Give your locks names that your keys don't use.
+
+### Managing locks across processes
+
+A lock can be taken in one process and released in another, such as a job the request dispatches. Each lock has an
+owner, a random string that `owner()` returns. Pass it to the job:
+
+```ts
+declare const id: number
+// @filename: app/Jobs/ProcessPodcast.ts
+import { Queueable } from '@orieljs/framework'
+import type { Podcast } from '../Models/Podcast'
+export class ProcessPodcast extends Queueable {
+  constructor(public podcast: Podcast, public owner: string) {
+    super()
+  }
+  async handle(): Promise<void> {}
+}
+// ---cut---
+const podcast = await Podcast.findOrFail(id)
+
+const lock = Cache.lock('processing', 120)
+
+if (await lock.get()) {
+  await ProcessPodcast.dispatch(podcast, lock.owner())
+}
+```
+
+In the job, `Cache.lock()` takes the owner as its third argument, and the lock it returns can release the one the
+request took:
+
+```ts title="app/Jobs/ProcessPodcast.ts"
+import { Cache, Queueable } from '@orieljs/framework'
+import type { Podcast } from '../Models/Podcast'
+
+export class ProcessPodcast extends Queueable {
+  constructor(
+    public podcast: Podcast,
+    public owner: string,
+  ) {
+    super()
+  }
+
+  async handle(): Promise<void> {
+    // ...
+
+    await Cache.lock('processing', 120, this.owner).release()
+  }
+}
+```
+
+`forceRelease()` releases a lock whoever owns it:
+
+```ts
+await Cache.lock('processing').forceRelease()
+```
+
+> [!NOTE]
+> Laravel restores a lock with `Cache::restoreLock()`; Oriel's `Cache.lock()` takes the owner instead. Laravel's
+> `withoutOverlapping()` and `funnel()` aren't in Oriel: take a lock with `block()`.
+
+## Rate limiting
+
+The `RateLimiter` counts how often something happens within a window of time, in the cache. The `throttle` route
+middleware uses it, and you can use it for anything else your app needs to limit. It keeps its counts in the store
+that `limiter` in `config/cache.ts` names, or in the default store.
+
+`hit()` adds one to a key's count, and starts the key's window, 60 seconds or the number you give, when the count
+starts. `tooManyAttempts()` tells you whether the count has reached a maximum within the window:
+
+```ts title="routes/web.ts"
+import { RateLimiter, request, Route } from '@orieljs/framework'
+import type { User } from '../app/Models/User'
+
+Route.post('/messages', async () => {
+  const user = await request().user<User>()
+  const key = `send-message:${user?.id}`
+
+  if (await RateLimiter.tooManyAttempts(key, 5)) {
+    const seconds = await RateLimiter.availableIn(key)
+
+    return `You may try again in ${seconds} seconds.`
+  }
+
+  await RateLimiter.hit(key, 60)
+
+  // Send the message...
+
+  return 'Sent.'
+})
+```
+
+Once the window ends, the count starts again from 0. The other methods:
+
+- `attempts(key)`: the count so far;
+- `remaining(key, max)`: how many are left before the maximum;
+- `availableIn(key)`: the seconds until the window ends;
+- `clear(key)`: forgets the count and the window.
+
+A key's accents don't count: `zoë` and `zoe` share a count.
+
+> [!NOTE]
+> Laravel's `RateLimiter::attempt()`, which runs a function while the count allows it, and `RateLimiter::for()`,
+> which names a limit for routes, aren't in Oriel. Check with `tooManyAttempts()` and count with `hit()`, as above.
+
+## Adding custom cache drivers
+
+### Writing the driver
+
+A driver is a store, which keeps the values, wrapped in a repository, which gives it the cache's API. Write the store
+as a class with the methods of the `CacheStore` type. This one keeps its values in a `Map`, as JSON; a store over
+another service has the same methods:
+
+```ts title="app/Extensions/MapStore.ts"
+import type { CacheStore } from '@orieljs/framework'
+
+interface Entry {
+  json: string
+  expiresAt: number
+}
+
+export class MapStore implements CacheStore {
+  private readonly entries = new Map<string, Entry>()
+
+  async get(key: string): Promise<unknown> {
+    const entry = this.live(key)
+    return entry === undefined ? undefined : JSON.parse(entry.json)
+  }
+
+  async many(keys: string[]): Promise<Record<string, unknown>> {
+    const found: Record<string, unknown> = {}
+    for (const key of keys) {
+      const entry = this.live(key)
+      if (entry !== undefined) found[key] = JSON.parse(entry.json)
+    }
+    return found
+  }
+
+  async put(key: string, value: unknown, seconds: number): Promise<boolean> {
+    this.entries.set(key, { json: JSON.stringify(value) ?? 'null', expiresAt: Date.now() + seconds * 1000 })
+    return true
+  }
+
+  async putForever(key: string, value: unknown): Promise<boolean> {
+    this.entries.set(key, { json: JSON.stringify(value) ?? 'null', expiresAt: Infinity })
+    return true
+  }
+
+  async add(key: string, value: unknown, seconds?: number): Promise<boolean> {
+    if (this.live(key) !== undefined) return false
+    const expiresAt = seconds === undefined ? Infinity : Date.now() + seconds * 1000
+    this.entries.set(key, { json: JSON.stringify(value) ?? 'null', expiresAt })
+    return true
+  }
+
+  async increment(key: string, by: number): Promise<number> {
+    const entry = this.live(key)
+    const next = (entry === undefined ? 0 : Number(JSON.parse(entry.json))) + by
+    this.entries.set(key, { json: String(next), expiresAt: entry?.expiresAt ?? Infinity })
+    return next
+  }
+
+  async decrement(key: string, by: number): Promise<number> {
+    return this.increment(key, -by)
+  }
+
+  async forget(key: string): Promise<boolean> {
+    return this.entries.delete(key)
+  }
+
+  async flush(): Promise<boolean> {
+    this.entries.clear()
+    return true
+  }
+
+  /** The key's entry, unless it is missing or has expired. */
+  private live(key: string): Entry | undefined {
+    const entry = this.entries.get(key)
+    return entry !== undefined && entry.expiresAt > Date.now() ? entry : undefined
+  }
+}
+```
+
+`get()` returns `undefined` for a missing or expired key, and `many()` leaves those keys out. `add()` must be atomic,
+since locks are built on it: this one checks and writes with no `await` in between. `increment()` starts a missing
+key at 0 and keeps an existing key's expiry. The repository deals with a missing number of seconds, and with zero or
+less, before your `put()` is called.
+
+### Registering the driver
+
+`Cache.extend()` registers the driver, with a function that receives the store's config and returns the repository.
+Do it in a service provider's `boot()`:
+
+```ts title="app/Providers/AppServiceProvider.ts"
+// @filename: app/Extensions/MapStore.ts
+import type { CacheStore } from '@orieljs/framework'
+export declare class MapStore implements CacheStore {
+  get(key: string): Promise<unknown>
+  many(keys: string[]): Promise<Record<string, unknown>>
+  put(key: string, value: unknown, seconds: number): Promise<boolean>
+  putForever(key: string, value: unknown): Promise<boolean>
+  add(key: string, value: unknown, seconds?: number): Promise<boolean>
+  increment(key: string, by: number): Promise<number>
+  decrement(key: string, by: number): Promise<number>
+  forget(key: string): Promise<boolean>
+  flush(): Promise<boolean>
+}
+// ---cut---
+import { Cache, CacheRepositoryImpl, ServiceProvider } from '@orieljs/framework'
+import { MapStore } from '../Extensions/MapStore'
+
+export class AppServiceProvider extends ServiceProvider {
+  override boot(): void {
+    Cache.extend('map', () => new CacheRepositoryImpl(new MapStore()))
+  }
+}
+```
+
+Then add a store with that driver to `config/cache.ts`, `map: { driver: 'map' }`, and name it in `CACHE_STORE` or in
+`Cache.store('map')`. The function receives the store's entry of `config/cache.ts`, with the cache's `prefix` when
+the entry has none of its own: a store that keeps other apps' keys too should start its keys with it. Locks on the
+new store are built on its `add()`.