Skip to content

Commit 5f621d4

Browse files
authored
Add docs and types for attachResource() & detachResource() (#110)
Category: addition
1 parent daf2a88 commit 5f621d4

8 files changed

+59
-9
lines changed

README.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -503,6 +503,16 @@ The optional `options` object may contain:
503503

504504
- `signal`: an [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to abort the deferred operation. When aborted (now or later) the `fn` function will not be called, and the promise returned by `deferAsync()` will be rejected with a [`LEVEL_ABORTED`](#level_aborted) error.
505505

506+
### `db.attachResource(resource)`
507+
508+
Keep track of the given `resource` in order to call its `close()` method when the database is closed. Once successfully closed, the resource will no longer be tracked, to the same effect as manually calling [`db.detachResource()`](#dbdetachresourceresource). When given multiple resources, the database will close them in parallel. Resources are kept in a [set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) so that the same object will not be attached (and closed) twice.
509+
510+
Intended for objects that rely on an open database. Used internally for built-in resources like iterators and sublevels, and is publicly exposed for custom resources.
511+
512+
### `db.detachResource(resource)`
513+
514+
Stop tracking the given `resource`.
515+
506516
### `iterator`
507517

508518
An iterator allows one to lazily read a range of entries stored in the database. The entries will be sorted by keys in [lexicographic order](https://en.wikipedia.org/wiki/Lexicographic_order) (in other words: byte order) which in short means key `'a'` comes before `'b'` and key `'10'` comes before `'2'`.

abstract-level.js

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -972,7 +972,6 @@ class AbstractLevel extends EventEmitter {
972972
})
973973
}
974974

975-
// TODO: docs and types
976975
attachResource (resource) {
977976
if (typeof resource !== 'object' || resource === null ||
978977
typeof resource.close !== 'function') {
@@ -982,7 +981,6 @@ class AbstractLevel extends EventEmitter {
982981
this.#resources.add(resource)
983982
}
984983

985-
// TODO: docs and types
986984
detachResource (resource) {
987985
this.#resources.delete(resource)
988986
}

index.d.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,8 @@ export {
4545
} from './types/abstract-snapshot'
4646

4747
export {
48-
AbstractReadOptions
48+
AbstractReadOptions,
49+
AbstractResource
4950
} from './types/interfaces'
5051

5152
export * as Transcoder from 'level-transcoder'

types/abstract-chained-batch.d.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
import * as Transcoder from 'level-transcoder'
22
import { AbstractSublevel } from './abstract-sublevel'
3+
import { AbstractResource } from './interfaces'
34

45
export class AbstractChainedBatch<TDatabase, KDefault, VDefault>
5-
implements AsyncDisposable {
6+
implements AbstractResource {
67
constructor (db: TDatabase)
78

89
/**

types/abstract-iterator.d.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import * as Transcoder from 'level-transcoder'
2-
import { AbstractReadOptions, RangeOptions } from './interfaces'
2+
import { AbstractReadOptions, AbstractResource, RangeOptions } from './interfaces'
33

44
declare interface CommonIteratorOptions extends AbstractReadOptions {
55
/**
@@ -60,7 +60,7 @@ export interface AbstractValueIteratorOptions<K, V> extends RangeOptions<K>, Com
6060
* @template TDatabase Type of the database that created this iterator.
6161
* @template T Type of items yielded. Items can be entries, keys or values.
6262
*/
63-
declare class CommonIterator<TDatabase, T> implements AsyncDisposable {
63+
declare class CommonIterator<TDatabase, T> implements AbstractResource {
6464
/**
6565
* A reference to the database that created this iterator.
6666
*/

types/abstract-level.d.ts

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import {
1414
AbstractValueIteratorOptions
1515
} from './abstract-iterator'
1616

17-
import { AbstractReadOptions, RangeOptions } from './interfaces'
17+
import { AbstractReadOptions, AbstractResource, RangeOptions } from './interfaces'
1818

1919
/**
2020
* Abstract class for a lexicographically sorted key-value database.
@@ -24,7 +24,7 @@ import { AbstractReadOptions, RangeOptions } from './interfaces'
2424
* @template VDefault The default type of values if not overridden on operations.
2525
*/
2626
declare class AbstractLevel<TFormat, KDefault = string, VDefault = string>
27-
extends EventEmitter implements AsyncDisposable {
27+
extends EventEmitter implements AbstractResource {
2828
/**
2929
* Private database constructor.
3030
*
@@ -307,6 +307,24 @@ declare class AbstractLevel<TFormat, KDefault = string, VDefault = string>
307307
* @returns A promise for the result of {@link fn}.
308308
*/
309309
deferAsync<T> (fn: () => Promise<T>, options?: AbstractDeferOptions | undefined): Promise<T>
310+
311+
/**
312+
* Keep track of the given {@link resource} in order to call its `close()` method when
313+
* the database is closed. Once successfully closed, the resource will no longer be
314+
* tracked, to the same effect as manually calling {@link detachResource}. When given
315+
* multiple resources, the database will close them in parallel. Resources are kept in
316+
* a {@link Set} so that the same object will not be attached (and closed) twice.
317+
*
318+
* Intended for objects that rely on an open database. Used internally for built-in
319+
* resources like iterators and sublevels, and is publicly exposed for custom
320+
* resources.
321+
*/
322+
attachResource(resource: AbstractResource): void
323+
324+
/**
325+
* Stop tracking the given {@link resource}.
326+
*/
327+
detachResource(resource: AbstractResource): void
310328
}
311329

312330
export { AbstractLevel }

types/abstract-snapshot.d.ts

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
1+
import { AbstractResource } from './interfaces'
2+
13
/**
24
* A lightweight token that represents a version of a database at a particular point in
35
* time.
46
*/
5-
export class AbstractSnapshot implements AsyncDisposable {
7+
export class AbstractSnapshot implements AbstractResource {
68
/**
79
* Increment reference count, to register work that should delay closing until
810
* {@link unref} is called an equal amount of times. The promise that will be returned

types/interfaces.d.ts

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,23 @@ export interface AbstractReadOptions {
2020
*/
2121
snapshot?: AbstractSnapshot | undefined
2222
}
23+
24+
/**
25+
* Represents a stateful resource that can be closed.
26+
*/
27+
export interface AbstractResource extends AsyncDisposable {
28+
/**
29+
* Close the resource.
30+
*
31+
* Note for implementors: if the resource is exposed to the user and can also be closed
32+
* in an automated fashion - through `db.attachResource()` or other - then the
33+
* `close()` method should be idempotent such that calling it twice will make no
34+
* difference.
35+
*/
36+
close (): Promise<void>
37+
38+
/**
39+
* Close the resource. Identical in functionality to {@link close}.
40+
*/
41+
[Symbol.asyncDispose](): Promise<void>
42+
}

0 commit comments

Comments
 (0)