feat!: kv set has expiration and ttl in seconds now

packages/iso-kv/src/index.js

@@ -45,7 +45,7 @@ function split(key) {
 }
 
 /**
- * UTC Unix timestamp in seconds
+ * Unix timestamp in seconds
  */
 const now = () => Math.floor(Date.now() / 1000)
 
@@ -151,19 +151,17 @@ export class KV {
    * @template [T=unknown]
    * @param {KvKey} key
    * @param {T} value
-   * @param {number} [ttl] - Time to live in seconds
+   * @param {import('./types').SetOptions} [options]
    */
-  async set(key, value, ttl) {
+  async set(key, value, options = {}) {
     if (value === undefined) {
       return this
     }
 
-    if (ttl === 0) {
-      ttl = undefined
-    }
+    const { ttl, expiration } = options
 
     // eslint-disable-next-line unicorn/no-null
-    const expires = typeof ttl === 'number' ? now() + ttl : null
+    const expires = expiration ?? (typeof ttl === 'number' ? now() + ttl : null)
 
     await this.#handleChange(key, value)
     await this.#driver.set(join(key), { value, expires })

packages/iso-kv/src/types.ts

@@ -64,6 +64,17 @@ The default value is false.
 
 export type KvListIterator<T> = IterableIterator<T> | AsyncIterableIterator<T>
 
+export interface SetOptions {
+  /**
+   * Time-to-live (TTL) for the key. The TTL is specified in seconds, and the key will be deleted from the database at earliest after the specified number of seconds have elapsed.
+   */
+  ttl?: number
+  /**
+   * Expiration time for the key. The expiration time is specified as a Unix timestamp in seconds since UNIX epoch, and the key will be deleted from the database at the specified time.
+   */
+  expiration?: number
+}
+
 export interface IKV {
   onChange: <T = unknown>(
     key: KvKey,
@@ -77,9 +88,9 @@ export interface IKV {
    *
    * @param key
    * @param value
-   * @param ttl - Time-to-live (TTL) for the key. The TTL is specified in milliseconds, and the key will be deleted from the database at earliest after the specified number of milliseconds have elapsed.
+   * @param options - {@link SetOptions}
    */
-  set: <T = unknown>(key: KvKey, value: T, ttl?: number) => Promise<IKV>
+  set: <T = unknown>(key: KvKey, value: T, options?: SetOptions) => Promise<IKV>
   delete: (key: KvKey) => Promise<void>
   clear: () => Promise<void>
   list: <T = unknown>(

packages/iso-kv/test/base.js

@@ -146,7 +146,7 @@ export function baseTests(kv, suite) {
   })
 
   test('should expires', async () => {
-    await kv.set(['foo'], 1, 1)
+    await kv.set(['foo'], 1, { ttl: 1 })
 
     await delay(2000)
 
@@ -155,16 +155,6 @@ export function baseTests(kv, suite) {
     assert.equal(value, undefined)
   })
 
-  test('should not expires with 0', async () => {
-    await kv.set(['should not expires with 0'], 1, 0)
-
-    await delay(100)
-
-    const value = await kv.get(['should not expires with 0'])
-
-    assert.equal(value, 1)
-  })
-
   test('should support data types', async () => {
     let v
     await kv.set(['undefined'], undefined)