Implement Symbol.asyncDispose (#95)

Per https://github.com/tc39/proposal-explicit-resource-management
which in TypeScript (5.2) allows you to skip calling `.close()`:

```ts
await db.put('example', 'before')
await using snapshot = db.snapshot()
await db.put('example', 'after')
await db.get('example', { snapshot })) // Returns 'before'
```

Works on databases, iterators, snapshots and batches.

Category: addition

Author: vweevers

README.md

@@ -61,6 +61,33 @@ const xyz = db.sublevel<string, any>('xyz', { valueEncoding: 'json' })
 
 </details>
 
+TypeScript users can benefit from the `using` keyword because `abstract-level` implements [`Symbol.asyncDispose`](https://github.com/tc39/proposal-explicit-resource-management) on its resources. For example:
+
+<details><summary>Using example</summary>
+
+```ts
+await db.put('example', 'before')
+await using snapshot = db.snapshot()
+await db.put('example', 'after')
+await db.get('example', { snapshot })) // Returns 'before'
+```
+
+The equivalent in JavaScript would be:
+
+```js
+await db.put('example', 'before')
+const snapshot = db.snapshot()
+
+try {
+  await db.put('example', 'after')
+  await db.get('example', { snapshot })) // Returns 'before'
+} finally {
+  await snapshot.close()
+}
+```
+
+</details>
+
 ## Install
 
 With [npm](https://npmjs.org) do:

abstract-chained-batch.js

@@ -358,6 +358,12 @@ class AbstractChainedBatch {
   async _close () {}
 }
 
+if (typeof Symbol.asyncDispose === 'symbol') {
+  AbstractChainedBatch.prototype[Symbol.asyncDispose] = async function () {
+    return this.close()
+  }
+}
+
 const prepareClose = function (batch) {
   let close
 

abstract-iterator.js

@@ -274,6 +274,12 @@ class CommonIterator {
   }
 }
 
+if (typeof Symbol.asyncDispose === 'symbol') {
+  CommonIterator.prototype[Symbol.asyncDispose] = async function () {
+    return this.close()
+  }
+}
+
 // For backwards compatibility this class is not (yet) called AbstractEntryIterator.
 class AbstractIterator extends CommonIterator {
   constructor (db, options) {

abstract-level.js

@@ -945,6 +945,12 @@ const { AbstractSublevel } = require('./lib/abstract-sublevel')({ AbstractLevel
 exports.AbstractLevel = AbstractLevel
 exports.AbstractSublevel = AbstractSublevel
 
+if (typeof Symbol.asyncDispose === 'symbol') {
+  AbstractLevel.prototype[Symbol.asyncDispose] = async function () {
+    return this.close()
+  }
+}
+
 const assertOpen = function (db) {
   if (db[kStatus] !== 'open') {
     throw new ModuleError('Database is not open', {

abstract-snapshot.js

@@ -70,6 +70,12 @@ class AbstractSnapshot {
   async _close () {}
 }
 
+if (typeof Symbol.asyncDispose === 'symbol') {
+  AbstractSnapshot.prototype[Symbol.asyncDispose] = async function () {
+    return this.close()
+  }
+}
+
 const privateClose = async function (snapshot, owner) {
   await snapshot._close()
   owner.detachResource(snapshot)

test/chained-batch-test.js

@@ -308,10 +308,24 @@ exports.tearDown = function (test, testCommon) {
   })
 }
 
+exports.dispose = function (test, testCommon) {
+  // Can't use the syntax yet (https://github.com/tc39/proposal-explicit-resource-management)
+  Symbol.asyncDispose && test('Symbol.asyncDispose', async function (t) {
+    const db = testCommon.factory()
+    await db.open()
+
+    const batch = db.batch()
+    await batch[Symbol.asyncDispose]()
+
+    return db.close()
+  })
+}
+
 exports.all = function (test, testCommon) {
   exports.setUp(test, testCommon)
   exports.args(test, testCommon)
   exports.batch(test, testCommon)
   exports.events(test, testCommon)
   exports.tearDown(test, testCommon)
+  exports.dispose(test, testCommon)
 }

test/iterator-explicit-snapshot-test.js

@@ -303,13 +303,27 @@ exports.cleanup = function (test, testCommon) {
   })
 }
 
+exports.dispose = function (test, testCommon) {
+  // Can't use the syntax yet (https://github.com/tc39/proposal-explicit-resource-management)
+  Symbol.asyncDispose && test('Symbol.asyncDispose', async function (t) {
+    const db = testCommon.factory()
+    await db.open()
+
+    const snapshot = db.snapshot()
+    await snapshot[Symbol.asyncDispose]()
+
+    return db.close()
+  })
+}
+
 exports.all = function (test, testCommon) {
   exports.traits(test, testCommon)
   exports.get(test, testCommon)
   exports.getMany(test, testCommon)
   exports.iterator(test, testCommon)
   exports.clear(test, testCommon)
   exports.cleanup(test, testCommon)
+  exports.dispose(test, testCommon)
 }
 
 function testFactory (test, testCommon) {

test/iterator-test.js

@@ -597,11 +597,25 @@ exports.tearDown = function (test, testCommon) {
   })
 }
 
+exports.dispose = function (test, testCommon) {
+  // Can't use the syntax yet (https://github.com/tc39/proposal-explicit-resource-management)
+  Symbol.asyncDispose && test('Symbol.asyncDispose', async function (t) {
+    const db = testCommon.factory()
+    await db.open()
+
+    const iterator = db.iterator()
+    await iterator[Symbol.asyncDispose]()
+
+    return db.close()
+  })
+}
+
 exports.all = function (test, testCommon) {
   exports.setUp(test, testCommon)
   exports.args(test, testCommon)
   exports.sequence(test, testCommon)
   exports.iterator(test, testCommon)
   exports.decode(test, testCommon)
   exports.tearDown(test, testCommon)
+  exports.dispose(test, testCommon)
 }

test/open-test.js

@@ -248,6 +248,14 @@ exports.open = function (test, testCommon) {
     await new Promise((resolve) => db.once('open', resolve))
     return db.close()
   })
+
+  // Can't use the syntax yet (https://github.com/tc39/proposal-explicit-resource-management)
+  Symbol.asyncDispose && test('Symbol.asyncDispose', async function (t) {
+    const db = testCommon.factory()
+    await db.open()
+    await db[Symbol.asyncDispose]()
+    t.is(db.status, 'closed')
+  })
 }
 
 exports.all = function (test, testCommon) {

types/abstract-chained-batch.d.ts

@@ -1,7 +1,8 @@
 import * as Transcoder from 'level-transcoder'
 import { AbstractSublevel } from './abstract-sublevel'
 
-export class AbstractChainedBatch<TDatabase, KDefault, VDefault> {
+export class AbstractChainedBatch<TDatabase, KDefault, VDefault>
+  implements AsyncDisposable {
   constructor (db: TDatabase)
 
   /**
@@ -53,6 +54,11 @@ export class AbstractChainedBatch<TDatabase, KDefault, VDefault> {
    * committing it.
    */
   close (): Promise<void>
+
+  /**
+   * Close the batch.
+   */
+  [Symbol.asyncDispose](): Promise<void>
 }
 
 /**