feat!: add adapter system for database store (#12)

Author: Julien-R44

docs/content/docs/cache_drivers.md

@@ -150,94 +150,67 @@ So using this function can be costly, both in terms of execution time and API re
 
 ## Databases
 
-We offer several drivers to use a database as a cache. Under the hood, we use [Knex](https://knexjs.org/). So all Knex options are available, feel free to check out the documentation.
+We offer several drivers to use a database as a cache. The database store should use an adapter for your database. Out of the box, we support [Knex](https://knexjs.org/) and [Kysely](https://kysely.dev/) to interact with the database. Knex and Kysely support many databases: SQLite, MySQL, PostgreSQL, MSSQL, Oracle, and more.
+
+:::note
+
+Note that you can easily create your own adapter by implementing the `DatabaseAdapter` interface if you are using another library not supported by Bentocache. See the [documentation](/docs/advanced/custom-adapters) for more details.
+
+:::
 
 All SQL drivers accept the following options:
 
 | Option | Description | Default |
 | --- | --- | --- |
 | `tableName` | The name of the table that will be used to store the cache. | `bentocache` |
 | `autoCreateTable` | If the cache table should be automatically created if it does not exist. | `true` |
-| `connection` | The connection options to use to connect to the database or an instance of `knex`. | N/A |
+| `connection` | An instance of `knex` or `Kysely` based on the driver. | N/A |
+| `pruneInterval` | The interval in milliseconds to prune expired entries. | `60000` |
 
-### PostgreSQL
+### Knex
 
-You will need to install `pg` to use this driver.
+You must provide a Knex instance to use the Knex driver. Feel free to check the [Knex documentation](https://knexjs.org/) for more details about the configuration. Knex support many databases : SQLite, MySQL, PostgreSQL, MSSQL, Oracle, and more.
 
 ```ts
+import knex from 'knex'
 import { BentoCache, bentostore } from 'bentocache'
-import { postgresDriver } from 'bentocache/drivers/sql'
-
-const bento = new BentoCache({
-  default: 'pg',
-  stores: {
-    pg: bentostore().useL2Layer(postgresDriver({
-      connection: { 
-        user: 'root', 
-        password: 'root', 
-        database: 'postgres', 
-        port: 5432 
-      }
-    }))
+import { knexDriver } from 'bentocache/drivers/knex'
+
+const db = knex({
+  client: 'pg',
+  connection: { 
+    port: 5432 
+    user: 'root', 
+    password: 'root', 
+    database: 'postgres', 
   }
 })
-```
-
-### MySQL
-
-You will need to install `mysql2` to use this driver.
-
-```ts
-import { BentoCache, bentostore } from 'bentocache'
-import { mysqlDriver } from 'bentocache/drivers/sql'
 
 const bento = new BentoCache({
-  default: 'mysql',
+  default: 'pg',
   stores: {
-    mysql: bentostore().useL2Layer(mysqlDriver({
-      connection: { 
-        user: 'root', 
-        password: 'root', 
-        database: 'mysql', 
-        port: 3306
-      },
-    }))
+    pg: bentostore().useL2Layer(knexDriver({ connection: db }))
   }
 })
 ```
 
-### SQLite ( better-sqlite3 )
-
-You will need to install `better-sqlite3` to use this driver.
+### Kysely
 
-```ts
-import { BentoCache, bentostore } from 'bentocache'
-import { betterSqliteDriver } from 'bentocache/drivers/sql'
+You must provide a Kysely instance to use the Kysely driver. Feel free to check the [Kysely documentation](https://kysely.dev/) for more details about the configuration. Kysely support the following databases : SQLite, MySQL, PostgreSQL and MSSQL.
 
-const bento = new BentoCache({
-  default: 'sqlite',
-  stores: {
-    sqlite: bentostore().useL2Layer(betterSqliteDriver({
-      connection: { filename: 'cache.sqlite3' },
-    }))
-  }
-})
-```
-
-### SQLite ( sqlite3 )
-
-You will need to install `sqlite3` to use this driver.
+You will need to install `mysql2` to use this driver.
 
 ```ts
+import { Kysely } from 'kysely'
 import { BentoCache, bentostore } from 'bentocache'
-import { sqliteDriver } from 'bentocache/drivers/sql'
+import { mysqlDriver } from 'bentocache/drivers/kysely'
+
+const db = new Kysely<Database>({ dialect })
 
 const bento = new BentoCache({
-  default: 'sqlite',
+  default: 'pg',
   stores: {
-    sqlite: bentostore().useL2Layer(sqliteDriver({
-      connection: { filename: 'cache.sqlite3' },
-    }))
+    pg: bentostore().useL2Layer(kyselyStore({ connection: db }))
   }
 })
 ```

docs/content/docs/extend/custom_cache_driver.md

@@ -94,6 +94,94 @@ const bento = new BentoCache({
 })
 ```
 
+## Create an adapter for the DatabaseDriver
+
+If your want to use a database to store your cache entries, you don't need to create a full driver. You can leverage the adapter system available with the database driver.
+
+We only ship adapter for Kysely and Knex to interact with the database for now. If ever you want to use another library, you can create your own adapter by implementing the `DatabaseAdapter` interface accessible from `bentocache/types`. The interface is defined as follows:
+
+```ts
+/**
+ * Interface for a DatabaseAdapter that can be used with the DatabaseDriver
+ */
+export interface DatabaseAdapter {
+  /**
+   * Set the table name for the adapter
+   */
+  setTableName(tableName: string): void
+
+  /**
+   * Get an entry from the database
+   */
+  get(key: string): Promise<{ value: any; expiresAt: number | null } | undefined>
+
+  /**
+   * Delete an entry from the database
+   *
+   * You should return true if the entry was deleted, false otherwise
+   */
+  delete(key: string): Promise<boolean>
+
+  /**
+   * Delete multiple entries from the database
+   *
+   * Should return the number of entries deleted
+   */
+  deleteMany(keys: string[]): Promise<number>
+
+  /**
+   * Disconnect from the database
+   */
+  disconnect(): Promise<void>
+
+  /**
+   * Create the cache table if it doesn't exist
+   *
+   * This method is responsible for checking it the table
+   * exists before creating it
+   */
+  createTableIfNotExists(): Promise<void>
+
+  /**
+   * Remove expired entries from the cache table
+   */
+  pruneExpiredEntries(): Promise<void>
+
+  /**
+   * Clear all entries from the cache table
+   */
+  clear(prefix: string): Promise<void>
+
+  /**
+   * Set a value in the cache
+   * You should also make sure to not create duplicate entries for the same key.
+   * Make sure to use `ON CONFLICT` or similar
+   */
+  set(row: { key: string; value: any; expiresAt: Date | null }): Promise<void>
+}
+```
+
+You can take a look at the code of the [Kysely adapter](https://github.com/Julien-R44/bentocache/blob/main/packages/bentocache/src/drivers/kysely.ts#L22) or the [Knex adapter](https://github.com/Julien-R44/bentocache/blob/main/packages/bentocache/src/drivers/kysely.ts#L22) for inspiration.
+
+Once you defined your adapter, you can create your own store that use the DatabaseDriver and your adapter:
+
+```ts
+export class PrismaAdapter implements DatabaseAdapter {
+  // ...
+}
+
+import { DatabaseDriver } from '@bentocache/drivers/database'
+
+export function prismaDriver(options: PrismaOptions): CreateDriverResult<DatabaseDriver> {
+  return {
+    config,
+    factory: () => {
+      const adapter = new PrismaAdapter(config)
+      return new DatabaseStore(adapter, config)
+    },
+  }
+}
+```
 ## Tests
 
 If you want to test your driver and its compliance, Bentocache is shipped with a test suite for [Japa](https://japa.dev/docs) that you can use. Note that you will also need to have `@japa/assert` installed. Then, you can use it like this:
@@ -106,11 +194,12 @@ import { MyDriver } from '../src/my_driver.js'
 
 test.group('My Driver', (group) => {
   registerCacheDriverTestSuite({
+    test,
     group,
-    driver: MyDriver,
-    config: {
-      // Your driver options
-    }
+    createDriver: (options) => new MyDriver({
+      myOption: 'myValue',
+      ...options
+    }),
   })
 })
 ```

packages/bentocache/benchmarks/mtier_get_key.ts

@@ -11,9 +11,9 @@ import { multiCaching, caching } from 'cache-manager'
 import { redisStore } from 'cache-manager-ioredis-yet'
 
 import { BentoCache } from '../index.js'
-import { redisDriver } from '../drivers/redis.js'
 import { bentostore } from '../src/bento_store.js'
-import { memoryDriver } from '../drivers/memory.js'
+import { redisDriver } from '../src/drivers/redis.js'
+import { memoryDriver } from '../src/drivers/memory.js'
 import { REDIS_CREDENTIALS } from '../test_helpers/index.js'
 
 const bench = new Bench()

packages/bentocache/benchmarks/mtier_set_key.ts

@@ -11,9 +11,9 @@ import { multiCaching, caching } from 'cache-manager'
 import { redisStore } from 'cache-manager-ioredis-yet'
 
 import { BentoCache } from '../index.js'
-import { redisDriver } from '../drivers/redis.js'
 import { bentostore } from '../src/bento_store.js'
-import { memoryDriver } from '../drivers/memory.js'
+import { redisDriver } from '../src/drivers/redis.js'
+import { memoryDriver } from '../src/drivers/memory.js'
 import { REDIS_CREDENTIALS } from '../test_helpers/index.js'
 
 const bench = new Bench()

packages/bentocache/benchmarks/onetier_get_key.ts

@@ -10,8 +10,8 @@ import { caching } from 'cache-manager'
 import { redisStore } from 'cache-manager-ioredis-yet'
 
 import { BentoCache } from '../index.js'
-import { redisDriver } from '../drivers/redis.js'
 import { bentostore } from '../src/bento_store.js'
+import { redisDriver } from '../src/drivers/redis.js'
 import { REDIS_CREDENTIALS } from '../test_helpers/index.js'
 
 const bench = new Bench()

packages/bentocache/benchmarks/onetier_set_key.ts

@@ -9,7 +9,7 @@ import { caching } from 'cache-manager'
 
 import { BentoCache } from '../index.js'
 import { bentostore } from '../src/bento_store.js'
-import { memoryDriver } from '../drivers/memory.js'
+import { memoryDriver } from '../src/drivers/memory.js'
 
 const bench = new Bench()