Document KV stores (#559)

Author: Murderlon

packages/file-store/README.md

@@ -53,16 +53,17 @@ The directory to store the files on disk (`string`).
 
 #### `options.configstore`
 
-Provide your own storage solution for the metadata of uploads (`Class`).
+Provide your own storage solution for the metadata of uploads ([`KvStore`][]).
 
-Default uses [`configstore`](https://www.npmjs.com/package/configstore).
+Default uses `FileKvStore` which puts the metadata file next to the uploaded file.
+See the exported [KV stores][kvstores] from `@tus/server` for more information.
 
 #### `options.expirationPeriodInMilliseconds`
 
 The time before an _ongoing_ upload is considered expired (`number`).
 
 This is since the time of creation, not modification. Once an upload is considered expired,
-uploads can be removed with [`cleanUpExpiredUploads`](https://github.com/tus/tus-node-server/tree/main/packages/server#)#servercleanupexpireduploads
+uploads can be removed with [`cleanUpExpiredUploads`][].
 
 ## Extensions
 
@@ -102,7 +103,7 @@ export class MemoryConfigstore {
     return this.data.delete(key)
   }
 
-  get all(): Record<string, Upload> {
+  get list(): Record<string, Upload> {
     return Object.fromEntries(this.data.entries())
   }
 }
@@ -139,3 +140,6 @@ See [`contributing.md`](https://github.com/tus/tus-node-server/blob/main/.github
 [checksum]: https://tus.io/protocols/resumable-upload.html#checksum
 [termination]: https://tus.io/protocols/resumable-upload.html#termination
 [concatenation]: https://tus.io/protocols/resumable-upload.html#concatenation
+[`cleanUpExpiredUploads`]: https://github.com/tus/tus-node-server/tree/main/packages/server#cleanupexpireduploads
+[kvstores]: https://github.com/tus/tus-node-server/tree/main/packages/server#kvstores
+[`KvStore`]: https://github.com/tus/tus-node-server/blob/main/packages/server/src/kvstores/Types.ts

packages/s3-store/README.md

@@ -71,7 +71,6 @@ Options to pass to the AWS S3 SDK.
 Checkout the [`S3ClientConfig`](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-s3/interfaces/s3clientconfig.html)
 docs for the supported options. You need to at least set the `region`, `bucket` name, and your preferred method of authentication.
 
-
 #### `options.expirationPeriodInMilliseconds`
 
 Enables the expiration extension and sets the expiration period of an upload url in milliseconds.
@@ -84,8 +83,13 @@ If you are using certain features like the expiration extension and your provide
 
 #### `options.cache`
 
-An optional cache implementation. If not provided, the store will use an in-memory cache (`MemoryConfigStore`).
-When running multiple instances of the server, you need to provide a cache implementation that is shared between all instances like the `RedisConfigStore`.
+An optional cache implementation ([`KvStore`][]).
+
+Default uses an in-memory cache (`MemoryKvStore`).
+When running multiple instances of the server,
+you need to provide a cache implementation that is shared between all instances like the `RedisKvStore`.
+
+See the exported [KV stores][kvstores] from `@tus/server` for more information.
 
 ## Extensions
 
@@ -181,3 +185,5 @@ See [`contributing.md`](https://github.com/tus/tus-node-server/blob/main/.github
 [concatenation]: https://tus.io/protocols/resumable-upload.html#concatenation
 [cleanExpiredUploads]: https://github.com/tus/tus-node-server/tree/main/packages/server#servercleanupexpireduploads
 [lifecyle]: https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html
+[kvstores]: https://github.com/tus/tus-node-server/tree/main/packages/server#kvstores
+[`KvStore`]: https://github.com/tus/tus-node-server/blob/main/packages/server/src/kvstores/Types.ts

packages/s3-store/index.ts

@@ -31,7 +31,7 @@ type Options = {
   s3ClientConfig: S3ClientConfig & {bucket: string}
 }
 
-type MetadataValue = {
+export type MetadataValue = {
   file: Upload
   'upload-id': string
   'tus-version': string

packages/server/README.md

@@ -50,8 +50,8 @@ server.listen({host, port})
 
 ## API
 
-This package exports `Server` and all [`constants`][], [`types`][], and [`models`][]. There is no default export.
-You should only need the `Server` and `EVENTS` exports.
+This package exports `Server` and all [`constants`][], [`types`][], [`models`][], and [`kvstores`][]. There is no default export.
+You should only need the `Server`, `EVENTS`, and KV store exports.
 
 ### `new Server(options)`
 
@@ -229,6 +229,57 @@ const {EVENTS} = require('@tus/server')
 server.on(EVENTS.POST_TERMINATE, (req, res, id => {})
 ```
 
+### Key-Value Stores
+
+All stores (as in the `datastore` option) save two files,
+the uploaded file and an info file with metadata, usually adjacent to each other.
+
+In `@tus/file-store` the `FileKvStore` is used to persist upload info but the KV stores
+can also be used as a cache in other stores, such as `@tus/s3-store`.
+
+#### `MemoryKvStore`
+
+```ts
+import {MemoryKvStore} from '@tus/server'
+import S3Store, {type MetadataValue} from '@tus/s3-store'
+
+new S3Store({
+  // ...
+  cache: new MemoryKvStore<MetadataValue>(),
+})
+```
+
+#### `FileKvStore`
+
+```ts
+import {FileKvStore} from '@tus/server'
+import S3Store, {type MetadataValue} from '@tus/s3-store'
+
+const path = './uploads'
+
+new S3Store({
+  // ...
+  cache: new FileKvStore<MetadataValue>(path),
+})
+```
+
+#### `RedisKvStore`
+
+```ts
+import {RedisKvStore} from '@tus/server'
+import S3Store, {type MetadataValue} from '@tus/s3-store'
+import {createClient} from '@redis/client'
+
+const client = await createClient().connect()
+const path = './uploads'
+const prefix = 'foo' // prefix for the key (foo${id})
+
+new S3Store({
+  // ...
+  cache: new RedisKvStore<MetadataValue>(client, prefix),
+})
+```
+
 ## Examples
 
 ### Example: integrate tus into Express
@@ -469,4 +520,5 @@ See [`contributing.md`](https://github.com/tus/tus-node-server/blob/main/.github
 [`constants`]: https://github.com/tus/tus-node-server/blob/main/packages/server/src/constants.ts
 [`types`]: https://github.com/tus/tus-node-server/blob/main/packages/server/src/types.ts
 [`models`]: https://github.com/tus/tus-node-server/blob/main/packages/server/src/models/index.ts
+[`kvstores`]: https://github.com/tus/tus-node-server/blob/main/packages/server/src/kvstores/index.ts
 [expiration]: https://tus.io/protocols/resumable-upload.html#expiration