feat: allow extending store method options (#193)

To allow for extra options like progress handlers, add generic types
for extending the options types passed to the various store methods.

They are all defaulted to an empty interface (e.g. no extension) so
this is a non-breaking change.

Author: achingbrain

packages/interface-blockstore/src/index.ts

@@ -1,20 +1,22 @@
 import type {
-  Options as StoreOptions,
+  AbortOptions,
   AwaitIterable,
   Store
 } from 'interface-store'
 import type { CID } from 'multiformats/cid'
 
-export interface Options extends StoreOptions {
-
-}
-
 export interface Pair {
   cid: CID
   block: Uint8Array
 }
 
-export interface Blockstore extends Store<CID, Uint8Array, Pair> {
+export interface Blockstore <HasOptionsExtension = {},
+PutOptionsExtension = {}, PutManyOptionsExtension = {},
+GetOptionsExtension = {}, GetManyOptionsExtension = {}, GetAllOptionsExtension = {},
+DeleteOptionsExtension = {}, DeleteManyOptionsExtension = {}> extends Store<CID, Uint8Array, Pair, HasOptionsExtension,
+  PutOptionsExtension, PutManyOptionsExtension,
+  GetOptionsExtension, GetManyOptionsExtension,
+  DeleteOptionsExtension, DeleteManyOptionsExtension> {
   /**
    * Retrieve all cid/block pairs from the blockstore as an unordered iterable
    *
@@ -26,5 +28,5 @@ export interface Blockstore extends Store<CID, Uint8Array, Pair> {
    * }
    * ```
    */
-  getAll: (options?: Options) => AwaitIterable<Pair>
+  getAll: (options?: AbortOptions & GetAllOptionsExtension) => AwaitIterable<Pair>
 }

packages/interface-datastore/src/index.ts

@@ -1,26 +1,32 @@
 import type {
-  Options as StoreOptions,
   Await,
-  Store
+  AwaitIterable,
+  Store,
+  AbortOptions
 } from 'interface-store'
 import { Key } from './key.js'
 
-export interface Options extends StoreOptions {
-
-}
-
 export interface Pair {
   key: Key
   value: Uint8Array
 }
 
-export interface Batch {
+export interface Batch<BatchOptionsExtension> {
   put: (key: Key, value: Uint8Array) => void
   delete: (key: Key) => void
-  commit: (options?: Options) => Await<void>
+  commit: (options?: AbortOptions & BatchOptionsExtension) => Await<void>
 }
 
-export interface Datastore extends Store<Key, Uint8Array, Pair> {
+export interface Datastore <HasOptionsExtension = {},
+PutOptionsExtension = {}, PutManyOptionsExtension = {},
+GetOptionsExtension = {}, GetManyOptionsExtension = {},
+DeleteOptionsExtension = {}, DeleteManyOptionsExtension = {},
+QueryOptionsExtension = {}, QueryKeysOptionsExtension = {},
+BatchOptionsExtension = {}
+> extends Store<Key, Uint8Array, Pair, HasOptionsExtension,
+  PutOptionsExtension, PutManyOptionsExtension,
+  GetOptionsExtension, GetManyOptionsExtension,
+  DeleteOptionsExtension, DeleteManyOptionsExtension> {
   /**
    * This will return an object with which you can chain multiple operations together, with them only being executed on calling `commit`.
    *
@@ -36,7 +42,7 @@ export interface Datastore extends Store<Key, Uint8Array, Pair> {
    * console.log('put 100 values')
    * ```
    */
-  batch: () => Batch
+  batch: () => Batch<BatchOptionsExtension>
 
   /**
    * Query the datastore.
@@ -51,7 +57,7 @@ export interface Datastore extends Store<Key, Uint8Array, Pair> {
    * console.log('ALL THE VALUES', list)
    * ```
    */
-  query: (query: Query, options?: Options) => AsyncIterable<Pair>
+  query: (query: Query, options?: AbortOptions & QueryOptionsExtension) => AwaitIterable<Pair>
 
   /**
    * Query the datastore.
@@ -66,7 +72,7 @@ export interface Datastore extends Store<Key, Uint8Array, Pair> {
    * console.log('ALL THE KEYS', key)
    * ```
    */
-  queryKeys: (query: KeyQuery, options?: Options) => AsyncIterable<Key>
+  queryKeys: (query: KeyQuery, options?: AbortOptions & QueryKeysOptionsExtension) => AwaitIterable<Key>
 }
 
 export interface QueryFilter { (item: Pair): boolean }

packages/interface-store/src/index.ts

@@ -1,15 +1,25 @@
 
+/**
+ * An iterable or async iterable of values
+ */
 export type AwaitIterable<T> = Iterable<T> | AsyncIterable<T>
+
+/**
+ * A value or a promise of a value
+ */
 export type Await<T> = Promise<T> | T
 
 /**
  * Options for async operations.
  */
-export interface Options {
+export interface AbortOptions {
   signal?: AbortSignal
 }
 
-export interface Store<Key, Value, Pair> {
+export interface Store<Key, Value, Pair, HasOptionsExtension = {},
+  PutOptionsExtension = {}, PutManyOptionsExtension = {},
+  GetOptionsExtension = {}, GetManyOptionsExtension = {},
+  DeleteOptionsExtension = {}, DeleteManyOptionsExtension = {}> {
   /**
    * Check for the existence of a value for the passed key
    *
@@ -24,7 +34,7 @@ export interface Store<Key, Value, Pair> {
    *}
    *```
    */
-  has: (key: Key, options?: Options) => Await<boolean>
+  has: (key: Key, options?: AbortOptions & HasOptionsExtension) => Await<boolean>
 
   /**
    * Store the passed value under the passed key
@@ -35,7 +45,7 @@ export interface Store<Key, Value, Pair> {
    * await store.put([{ key: new Key('awesome'), value: new Uint8Array([0, 1, 2, 3]) }])
    * ```
    */
-  put: (key: Key, val: Value, options?: Options) => Await<void>
+  put: (key: Key, val: Value, options?: AbortOptions & PutOptionsExtension) => Await<void>
 
   /**
    * Store the given key/value pairs
@@ -51,7 +61,7 @@ export interface Store<Key, Value, Pair> {
    */
   putMany: (
     source: AwaitIterable<Pair>,
-    options?: Options
+    options?: AbortOptions & PutManyOptionsExtension
   ) => AwaitIterable<Pair>
 
   /**
@@ -64,7 +74,7 @@ export interface Store<Key, Value, Pair> {
    * // => got content: datastore
    * ```
    */
-  get: (key: Key, options?: Options) => Await<Value>
+  get: (key: Key, options?: AbortOptions & GetOptionsExtension) => Await<Value>
 
   /**
    * Retrieve values for the passed keys
@@ -79,7 +89,7 @@ export interface Store<Key, Value, Pair> {
    */
   getMany: (
     source: AwaitIterable<Key>,
-    options?: Options
+    options?: AbortOptions & GetManyOptionsExtension
   ) => AwaitIterable<Value>
 
   /**
@@ -92,7 +102,7 @@ export interface Store<Key, Value, Pair> {
    * console.log('deleted awesome content :(')
    * ```
    */
-  delete: (key: Key, options?: Options) => Await<void>
+  delete: (key: Key, options?: AbortOptions & DeleteOptionsExtension) => Await<void>
 
   /**
    * Remove values for the passed keys
@@ -109,6 +119,6 @@ export interface Store<Key, Value, Pair> {
    */
   deleteMany: (
     source: AwaitIterable<Key>,
-    options?: Options
+    options?: AbortOptions & DeleteManyOptionsExtension
   ) => AwaitIterable<Key>
 }