import { RowObject, RowValues, Transaction, TransactionResult, TransactionInput, Statement } from '../sdk/transaction.js'; import { Logger } from '../sdk/logger.js'; import { z } from 'zod'; import { ByteStream } from '../streams/index.js'; declare type EventType$1 = string | symbol; declare type Handler = (event: T) => void; declare type WildcardHandler> = (type: keyof T, event: T[keyof T]) => void; declare type EventHandlerList = Array>; declare type WildCardEventHandlerList> = Array>; declare type EventHandlerMap> = Map | WildCardEventHandlerList>; interface Emitter> { all: EventHandlerMap; on(type: Key, handler: Handler): void; on(type: '*', handler: WildcardHandler): void; off(type: Key, handler?: Handler): void; off(type: '*', handler: WildcardHandler): void; emit(type: Key, event: Events[Key]): void; emit(type: undefined extends Events[Key] ? Key : never): void; } //#region src/errors/lib/auth.d.ts declare class MissingCredentialsError extends Error { static readonly name = "MissingCredentialsError"; constructor(msg?: string); } declare class InvalidCredentialsError extends Error { static readonly name = "InvalidCredentialsError"; constructor(msg?: string); } declare class ExpiredCredentialsError extends Error { static readonly name = "ExpiredCredentialsError"; constructor(msg?: string); } //#endregion //#region src/errors/lib/feature.d.ts declare class FeatureNotImplementedError extends Error { static readonly name = "FeatureNotImplementedError"; constructor(msg?: string); } //#endregion //#region src/errors/lib/network.d.ts declare class NetworkError extends Error { static readonly name = "NetworkError"; constructor(msg?: string); } //#endregion //#region src/errors/lib/request.d.ts declare class BadRequestError extends Error { static readonly name = "BadRequestError"; constructor(msg: string); } //#endregion //#region src/errors/lib/resource.d.ts declare class ResourceNotFoundError extends Error { static readonly name = "ResourceNotFoundError"; readonly resource?: Selector; constructor(resource?: Selector); } declare class ResourceExistsError extends Error { static readonly name = "ResourceExistsError"; readonly resource?: Selector; constructor(resource?: Selector); } declare class ResourceNotAccessibleError extends Error { static readonly name = "ResourceNotAccessibleError"; readonly resource?: Selector; constructor(resource?: Selector); } declare class ResourceNotInitializedError extends Error { static readonly name = "ResourceNotInitializedError"; readonly resource?: Selector; constructor(resource?: Selector); } //#endregion //#region src/errors/lib/selector.d.ts declare class InvalidSelectorError extends Error { static readonly name = "InvalidSelectorError"; constructor(selector?: Selector); } declare class InvalidSelectorKeyError extends Error { static readonly name = "InvalidSelectorKeyError"; constructor(key: string); } //#endregion //#region src/errors/lib/sqlite.d.ts declare class InvalidBinaryContentsError extends Error { static readonly name = "InvalidBinaryContentsError"; constructor(msg?: string); } //#endregion //#region src/errors/lib/transaction.d.ts declare class StatementPreparationError extends Error { static readonly name = "StatementPreparationError"; readonly statement?: Statement; constructor(msg: string, statement: Statement); } declare class StatementExecutionError extends Error { static readonly name = "StatementExecutionError"; readonly statement?: Statement; constructor(msg: string, statement: Statement); } //#endregion //#region src/errors/index.d.ts declare const SerializedErrorSchema: z.ZodObject<{ name: z.ZodString; message: z.ZodString; props: z.ZodOptional>; }, z.core.$strip>; type SerializedError = z.infer; declare const KNOWN_ERRORS: Map) => Error>; /** * Utility for serializing an `Error`-like object into a JSON object, * allowing for it to be transferred across process boundaries. * * For security reasons, the `stack` property is not included in the * serialized error object. * * @param error `Error`-like object to serialize. * * @returns JSON-compatible `SerializedError` object. */ declare const serializeError: (error: Error) => SerializedError; /** * Utility for deserializing a `SerializedError` object into an actual * error instance. * * @param serialized `SerializedError` object to deserialize. * @param constructors Map of error constructors. * * @returns Deserialized error instance. */ declare const deserializeError: (serialized: SerializedError, constructors: Map) => T>) => T; //#endregion //#region src/events/lib/base.d.ts type BaseEventConfig = { id?: string | null | undefined; trace?: Trace | null | undefined; }; declare abstract class BaseEvent { /** * Unique event identifier. */ readonly id: string; /** * Trace identifier. */ readonly trace: Trace; constructor(config?: BaseEventConfig); } type SerializedBaseEvent = { id: string; trace: Trace; }; //#endregion //#region src/events/lib/error.d.ts declare class UnexpectedErrorEvent extends BaseEvent { static readonly type: "unexpected-error"; readonly type: "unexpected-error"; /** * `Error` instance that was thrown and captured. */ readonly error: Error; constructor(config: BaseEventConfig & { error: Error; }); readonly serialize: () => SerializedUnexpectedErrorEvent; } type SerializedUnexpectedErrorEvent = SerializedBaseEvent & { type: typeof UnexpectedErrorEvent.type; error: SerializedError; }; type UnexpectedErrorEventType = typeof UnexpectedErrorEvent.type; interface UnexpectedErrorEventMap { [UnexpectedErrorEvent.type]: UnexpectedErrorEvent; } //#endregion //#region src/events/lib/index.d.ts declare class IndexStartEvent extends BaseEvent { static readonly type: "index:start"; readonly type: "index:start"; readonly serialize: () => SerializedIndexStartEvent; } type SerializedIndexStartEvent = SerializedBaseEvent & { type: typeof IndexStartEvent.type; }; declare class IndexStopEvent extends BaseEvent { static readonly type: "index:stop"; readonly type: "index:stop"; readonly serialize: () => SerializedIndexStopEvent; } type SerializedIndexStopEvent = SerializedBaseEvent & { type: typeof IndexStopEvent.type; }; declare class IndexRefreshEvent extends BaseEvent { static readonly type: "index:refresh"; readonly type: "index:refresh"; readonly parent: Selector<'namespace' | 'database'> | null | undefined; constructor(config: BaseEventConfig & { parent: Selector<'namespace' | 'database'> | null | undefined; }); readonly serialize: () => SerializedIndexRefreshEvent; } type SerializedIndexRefreshEvent = SerializedBaseEvent & { type: typeof IndexRefreshEvent.type; parent: Selector<'namespace' | 'database'> | null | undefined; }; type SerializedIndexEvent = SerializedIndexStartEvent | SerializedIndexStopEvent | SerializedIndexRefreshEvent; type IndexEventType = typeof IndexStartEvent.type | typeof IndexStopEvent.type | typeof IndexRefreshEvent.type; interface IndexEventMap { [IndexStartEvent.type]: IndexStartEvent; [IndexStopEvent.type]: IndexStopEvent; [IndexRefreshEvent.type]: IndexRefreshEvent; } //#endregion //#region src/events/lib/instance.d.ts declare class InstanceStartEvent extends BaseEvent { static readonly type: "instance:start"; readonly type: "instance:start"; readonly serialize: () => SerializedInstanceStartEvent; } type SerializedInstanceStartEvent = SerializedBaseEvent & { type: typeof InstanceStartEvent.type; }; declare class InstanceStopEvent extends BaseEvent { static readonly type: "instance:stop"; readonly type: "instance:stop"; readonly serialize: () => SerializedInstanceStopEvent; } type SerializedInstanceStopEvent = SerializedBaseEvent & { type: typeof InstanceStopEvent.type; }; type SerializedHiveEvent = SerializedInstanceStartEvent | SerializedInstanceStopEvent; type HiveEventType = typeof InstanceStartEvent.type | typeof InstanceStopEvent.type; interface HiveEventMap { [InstanceStartEvent.type]: InstanceStartEvent; [InstanceStopEvent.type]: InstanceStopEvent; } //#endregion //#region src/events/lib/resource.d.ts declare class ResourceGetSizeEvent extends BaseEvent { static readonly type: "resource:get-size"; readonly type: "resource:get-size"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedResourceGetSizeEvent; } type SerializedResourceGetSizeEvent = SerializedBaseEvent & { type: typeof ResourceGetSizeEvent.type; resource: Selector['key']; }; declare class ResourceGetMetadataEvent extends BaseEvent { static readonly type: "resource:get-metadata"; readonly type: "resource:get-metadata"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedResourceGetMetadataEvent; } type SerializedResourceGetMetadataEvent = SerializedBaseEvent & { type: typeof ResourceGetMetadataEvent.type; resource: Selector['key']; }; declare class ResourceGetContentsEvent extends BaseEvent { static readonly type: "resource:get-contents"; readonly type: "resource:get-contents"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedResourceGetContentsEvent; } type SerializedResourceGetContentsEvent = SerializedBaseEvent & { type: typeof ResourceGetContentsEvent.type; resource: Selector['key']; }; declare class ResourceSetContentsEvent extends BaseEvent { static readonly type: "resource:set-contents"; readonly type: "resource:set-contents"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedResourceSetContentsEvent; } type SerializedResourceSetContentsEvent = SerializedBaseEvent & { type: typeof ResourceSetContentsEvent.type; resource: Selector['key']; }; declare class ResourceTransactionEvent extends BaseEvent { static readonly type: "resource:transaction"; readonly type: "resource:transaction"; readonly resource: Selector; readonly transaction: Transaction; constructor(config: BaseEventConfig & { resource: Selector; transaction: Transaction; }); readonly serialize: () => SerializedResourceTransactionEvent; } type SerializedResourceTransactionEvent = SerializedBaseEvent & { type: typeof ResourceTransactionEvent.type; resource: Selector['key']; transaction: Transaction; }; declare class ResourceCloseEvent extends BaseEvent { static readonly type: "resource:close"; readonly type: "resource:close"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedResourceCloseEvent; } type SerializedResourceCloseEvent = SerializedBaseEvent & { type: typeof ResourceCloseEvent.type; resource: Selector['key']; }; type SerializedResourceEvent = SerializedResourceGetSizeEvent | SerializedResourceGetMetadataEvent | SerializedResourceGetContentsEvent | SerializedResourceSetContentsEvent | SerializedResourceTransactionEvent | SerializedResourceCloseEvent; type ResourceEventType = typeof ResourceGetSizeEvent.type | typeof ResourceGetMetadataEvent.type | typeof ResourceGetContentsEvent.type | typeof ResourceSetContentsEvent.type | typeof ResourceTransactionEvent.type | typeof ResourceCloseEvent.type; interface ResourceEventMap { [ResourceGetSizeEvent.type]: ResourceGetSizeEvent; [ResourceGetMetadataEvent.type]: ResourceGetMetadataEvent; [ResourceGetContentsEvent.type]: ResourceGetContentsEvent; [ResourceSetContentsEvent.type]: ResourceSetContentsEvent; [ResourceTransactionEvent.type]: ResourceTransactionEvent; [ResourceCloseEvent.type]: ResourceCloseEvent; } //#endregion //#region src/events/lib/storage.d.ts declare class StorageStartEvent extends BaseEvent { static readonly type: "storage:start"; readonly type: "storage:start"; readonly serialize: () => SerializedStorageStartEvent; } type SerializedStorageStartEvent = SerializedBaseEvent & { type: typeof StorageStartEvent.type; }; declare class StorageStopEvent extends BaseEvent { static readonly type: "storage:stop"; readonly type: "storage:stop"; readonly serialize: () => SerializedStorageStopEvent; } type SerializedStorageStopEvent = SerializedBaseEvent & { type: typeof StorageStopEvent.type; }; declare class StorageCreateEvent extends BaseEvent { static readonly type: "storage:create"; readonly type: "storage:create"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedStorageCreateEvent; } type SerializedStorageCreateEvent = SerializedBaseEvent & { type: typeof StorageCreateEvent.type; resource: Selector['key']; }; declare class StorageListEvent extends BaseEvent { static readonly type: "storage:list"; readonly type: "storage:list"; readonly parent: Selector | null; readonly results: number; constructor(config: BaseEventConfig & { parent: Selector | null; results: number; }); readonly serialize: () => SerializedStorageListEvent; } type SerializedStorageListEvent = SerializedBaseEvent & { type: typeof StorageListEvent.type; parent: Selector['key'] | null; results: number; }; declare class StorageHasEvent extends BaseEvent { static readonly type: "storage:has"; readonly type: "storage:has"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedStorageHasEvent; } type SerializedStorageHasEvent = SerializedBaseEvent & { type: typeof StorageHasEvent.type; resource: Selector['key']; }; declare class StorageGetEvent extends BaseEvent { static readonly type: "storage:get"; readonly type: "storage:get"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedStorageGetEvent; } type SerializedStorageGetEvent = SerializedBaseEvent & { type: typeof StorageGetEvent.type; resource: Selector['key']; }; declare class StorageFreeEvent extends BaseEvent { static readonly type: "storage:free"; readonly type: "storage:free"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedStorageFreeEvent; } type SerializedStorageFreeEvent = SerializedBaseEvent & { type: typeof StorageFreeEvent.type; resource: Selector['key']; }; declare class StorageDeleteEvent extends BaseEvent { static readonly type: "storage:delete"; readonly type: "storage:delete"; readonly resource: Selector; constructor(config: BaseEventConfig & { resource: Selector; }); readonly serialize: () => SerializedStorageDeleteEvent; } type SerializedStorageDeleteEvent = SerializedBaseEvent & { type: typeof StorageDeleteEvent.type; resource: Selector['key']; }; type StorageEvent = StorageStartEvent | StorageStopEvent | StorageCreateEvent | StorageListEvent | StorageHasEvent | StorageGetEvent | StorageFreeEvent | StorageDeleteEvent; type StorageEventType = typeof StorageStartEvent.type | typeof StorageStopEvent.type | typeof StorageCreateEvent.type | typeof StorageListEvent.type | typeof StorageHasEvent.type | typeof StorageGetEvent.type | typeof StorageFreeEvent.type | typeof StorageDeleteEvent.type; interface StorageEventMap { [StorageStartEvent.type]: StorageStartEvent; [StorageStopEvent.type]: StorageStopEvent; [StorageCreateEvent.type]: StorageCreateEvent; [StorageListEvent.type]: StorageListEvent; [StorageHasEvent.type]: StorageHasEvent; [StorageGetEvent.type]: StorageGetEvent; [StorageFreeEvent.type]: StorageFreeEvent; [StorageDeleteEvent.type]: StorageDeleteEvent; } //#endregion //#region src/events/index.d.ts type EventType = HiveEventType | UnexpectedErrorEventType | IndexEventType | ResourceEventType | StorageEventType; interface EventMap extends HiveEventMap, UnexpectedErrorEventMap, IndexEventMap, ResourceEventMap, StorageEventMap {} type ListenerFor, K extends keyof T = keyof T> = { bivarianceHack(payload: T[K]): void; }['bivarianceHack']; type Listener, K extends keyof T = keyof T> = ListenerFor; declare class EventEmitter { /** * Internal `EventEmitter` instance. */ readonly emitter: Emitter; /** * Register a new event listener. * * @param event Name of the event to listen for. * @param listener Function to call when the event is emitted. * * @returns `this` to allow chaining. */ on(event: K, listener: Listener>): this; /** * Remove an event listener. * * @param event Name of the event to remove the listener from. * @param listener Function to remove from the event. * * @returns `this` to allow chaining. */ off(event: K, listener: Listener>): this; /** * Emit an event. * * @param event Name of the event to emit. * @param payload Payload to pass to the event listener. * * @returns void */ emit(event: K, payload: T[K]): void; } //#endregion //#region src/operation.d.ts type Trace = string; type OperationConfig = { id?: string | null | undefined; type?: EventType | null | undefined; trace?: Trace | null | undefined; start?: number | null | undefined; end?: number | null | undefined; }; type SerializedOperation = { id: string; type: EventType | null; trace: Trace | null; start: number; end: number | null; }; declare class Operation { /** * Unique identifier of the `Operation`. */ readonly id: string; /** * Optionally, a predefined type of the `Operation` as used internally * by the `Hive` instance and its core components. * * Allows for grouping related events and filtering them. */ readonly type: EventType | null; /** * Optionally, a trace identifier for the `Operation`. * * Primarily used for tracing and filtering. */ readonly trace: Trace | null; /** * Timestamp of when the `Operation` started. */ readonly start: number; /** * Timestamp of when the `Operation` ended. */ end: number | null; constructor(config?: OperationConfig); /** * Duration of how long the `Operation` took to complete. */ get duration(): number; /** * Serializes the `Operation` into a plain JSON-like object. * * @returns Object matching the `SerializedOperation` type. */ readonly serialize: () => SerializedOperation; } //#endregion //#region src/connection.d.ts /** * A `Connection` wraps a runtime-specific implementation of an open * SQLite Database connection with additional functionality. */ declare abstract class Connection { /** * Execute a Transaction against the SQLite database. * * @param transaction Transaction to execute against the SQLite database. * @param opts Options for executing the transaction. * * @returns Promise resolving the results of the Transaction. */ abstract query: = ReadonlyArray>(transaction: Transaction, opts?: { trace?: Trace | null | undefined; }) => Promise>; /** * Close the `Connection` instance. * * @param opts Options for closing the `Connection` instance. * * @returns Promise resolving when the `Connection` instance has been closed. */ abstract close: (opts?: { trace?: Trace | null | undefined; }) => Promise; /** * Get the size of the Database binary contents in bytes. * * @returns Promise resolving to the size of the Database binary contents * in bytes. */ abstract getSize: () => Promise; /** * Get the binary contents of the Database. * * @returns Promise resolving to the binary contents of the Database. */ abstract getContents: () => Promise; } //#endregion //#region src/driver.d.ts interface DriverStartOptions { logger?: Logger | null | undefined; onError?: ((event: UnexpectedErrorEvent) => void) | null | undefined; } /** * A `Driver` wraps a runtime-specific implementation of SQLite. */ declare abstract class Driver { /** * Start the `Driver` instance. * * @param opts Options for starting the `Driver` instance. * * @returns Promise resolving the `Driver` instance. * * @throws `Error` if an error prevents the `Driver` from starting. */ abstract start(opts: DriverStartOptions & { trace?: Trace | null | undefined; }): Promise; /** * Stop the `Driver` instance and clean up any resources it is managing. * * @param opts Options for stopping the `Driver` instance. * * @returns Promise resolving the `Driver` instance. * * @throws `Error` if an error prevents the `Driver` from stopping. */ abstract stop(opts?: { trace?: Trace | null | undefined; }): Promise; /** * Open a `Connection` for an SQLite Database. * * @example ```ts * // In-memory SQLite Database. * const db = await driver.open(); * ``` * * @example ```ts * // SQLite Database persisted on disk. * const db = await driver.open(db.path); * ``` * * @param contents Contents to open the `Connection` instance with. * @param opts Additional options for creating the `Connection` instance. * * @returns Promise resolving a `Connection` instance. * * @throws `Error` if the provided binary contents are not a valid * SQLite Database. * * @throws `Error` if no Database is found at the specified path. */ abstract open: (contents: Uint8Array | string, opts?: { trace?: Trace | null | undefined; }) => Promise; } //#endregion //#region src/namespace.d.ts type NamespaceMetadata = { key: string; type: 'namespace'; parent: Selector['key'] | null; indexedAt: Date; createdAt: Date | null; modifiedAt: Date | null; }; type NamespaceConfig = Omit & { /** * Unique identifier of the Namespace within the scope of its parent. * * @default `'main'` */ id?: string | null | undefined; /** * Parent of the Namespace. * * @default `null` */ parent?: Selector['key'] | Selector<'namespace'> | null | undefined; /** * `Storage` instance to use for persisting the Namespace. * * If not passed, the Namespace must be initialized by passing it to either * `hive.create()` or `hive.get()`. * * @default `null` */ storage?: Storage | null | undefined; }; declare class Namespace extends Selector<'namespace'> { /** * `Storage` instance to use for persisting the Namespace. * * If not set, the Namespace must be initialized by passing it to either * `hive.create()` or `hive.get()`. */ storage: Storage | null; constructor(config?: NamespaceConfig | null | undefined); /** * Get the metadata stored for the Namespace. * * @param opts Options for getting the metadata stored for the Namespace. * * @returns Promise resolving with the metadata stored for the Namespace. * * @throws `ResourceNotFoundError` if the Namespace was not found. * @throws `ResourceNotInitializedError` if the Namespace is not initialized. * To initialize the Namespace, pass it to either `hive.create()` or `hive.get()`. */ readonly getMetadata: (opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; }) => Promise; } //#endregion //#region src/storage.d.ts interface StorageStartOptions { driver: Driver | null | undefined; events: EventEmitter | null | undefined; logger: Logger | null | undefined; onError: ((event: UnexpectedErrorEvent) => void) | null | undefined; } type CreateResourceOptions = S['type'] extends 'namespace' ? { /** * Trace to associate the operation with. * * @default () => crypto.randomUUID() */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageCreateEvent` when the Resource has been * created. * * @default true */ emit?: boolean | null | undefined; /** * Whether to check if the parent Resource exists before creating the * contents of the Resource. * * @default true */ checkParent?: boolean | null | undefined; } : { /** * Trace to associate the operation with. * * @default () => crypto.randomUUID() */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageCreateEvent` when the Resource has been * created. * * @default true */ emit?: boolean | null | undefined; /** * Whether to check if the parent Resource exists before creating the * contents of the Resource. * * @default true */ checkParent?: boolean | null | undefined; /** * For Databases, optional contents to set for the Database. * * Can either * * @default null * * @example ``` * // With contents from a `Uint8Array`. * const contents = await readFile('my-db.sqlite'); * const db = await storage.create({ type: 'database', id: 'my-db' }, { contents }); * ``` * * @example ``` * // With contents from a `ByteStream`. * const contents = await streamFile('my-db.sqlite'); * const db = await storage.create({ type: 'database', id: 'my-db' }, { contents }); * ``` * * @example ``` * // With contents copied from another Database. * const source = new Selector({ type: 'database', id: 'source-db' }); * const db = await storage.create({ type: 'database', id: 'my-db' }, { contents: source }); * ``` */ contents?: ByteStream | Uint8Array | Selector<'database' | 'snapshot' | 'branch'> | null | undefined; }; /** * `Storage` instances are responsible for managing the persistence of * Resources. They facilitate the creation, retrieval, listing, and deletion * of Resources across different storage backends such as local disk, memory, * or cloud services like S3. * * Storage implementations handle the low-level details of where and how * Resource data is persisted, providing a consistent interface for the * rest of the system to interact with stored Resources regardless of * the underlying storage mechanism. */ declare abstract class Storage { /** * Start the `Storage` instance. * * @param opts Options for starting the `Storage` instance. * * @returns Promise resolving once the `Storage` instance has started. * * @throws `Error` if an error prevents the `Storage` from starting. * * @emits `StorageStartEvent` when the `Storage` instance has started. */ abstract start(opts: StorageStartOptions & { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageStartEvent` when the `Storage` instance * has started. * * @default `true` */ emit?: boolean | null | undefined; }): Promise; /** * Stop the `Storage` instance. * * @param opts Options for stopping the `Storage` instance. * * @returns Promise resolving with the `Storage` instance. * * @throws `Error` if an error prevents the `Storage` from stopping. * * @emits `StorageStopEvent` when the `Storage` instance has stopped. */ abstract stop(opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageStopEvent` when the `Storage` instance * has stopped. * * @default `true` */ emit?: boolean | null | undefined; }): Promise; /** * Create a new `Resource` with the provided contents. * * @param selector Selector of the Resource to create. * @param contents Contents of the Resource. * @param opts Options for creating the Resource. * * @example ``` * // With contents from a `Uint8Array`. * const contents = await readFile('my-db.sqlite'); * const db = await storage.create({ type: 'database', id: 'my-db' }, { contents }); * ``` * * @example ``` * // With contents from a `ByteStream`. * const contents = await streamFile('my-db.sqlite'); * const db = await storage.create({ type: 'database', id: 'my-db' }, { contents }); * ``` * * @example ``` * // With contents copied from another Database. * const source = new Selector({ type: 'database', id: 'source-db' }); * const db = await storage.create({ type: 'database', id: 'my-db' }, { contents: source }); * ``` * * @returns Promise resolving with the created Resource and its metadata. * * @throws `ResourceExistsError` if the Resource already exists. * @throws `ResourceNotFoundError` if the parent Resource does not exist. * @throws `InvalidBinaryContentsError` if the provided contents are invalid. * * @emits `StorageCreateEvent` when the Resource has been created. */ abstract create(selector: S, opts?: CreateResourceOptions): Promise<{ resource: InstanceFor; metadata: MetadataFor; }>; /** * List Resources managed by the `Storage` instance. * * @param opts Options for listing Resources. * * @example ```ts * // List all top-level Resources. * const resources = await storage.list(); * ``` * * @example ```ts * // List all child Resources of a specific Resource. * const children = await storage.list({ * parent: { * type: 'database', * id: 'my-db', * }, * }); * ``` * * @returns Promise resolving an Array containing the Metadata for the * listed Resources. * * @throws `ResourceNotFoundError` if the parent Resource does not exist. * * @emits `StorageListEvent` when Resources have been listed. */ abstract list(opts?: { /** * Selector of the parent Resource to list all child Resources of. * * @default `null` */ parent?: Selector<'namespace' | 'database'> | null | undefined; /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageListEvent` when the Resources have been * listed. * * @default `true` */ emit?: boolean | null | undefined; /** * Whether to use the Index to list Resources. * * @default `true` */ index?: boolean | null | undefined; }): Promise>; /** * Check if a specific Resource is managed by the `Storage` instance. * * @param selector Selector of the Resource to check. * @param opts Options for checking the Resource. * * @returns Promise resolving a boolean indicating whether the Resource * is managed by the `Storage` instance. * * @emits `StorageHasEvent` when the Resource has been checked. */ abstract has(selector: Selector, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageHasEvent` when the Resource has been * checked. * * @default `true` */ emit?: boolean | null | undefined; }): Promise; /** * Get an instance of a specific Resource. * * @param selector Selector of the Resource to get. * @param opts Options for getting the Resource. * * @returns Promise resolving the requested Resource and its metadata. * * @throws `ResourceNotFoundError` if the Resource was not found. * * @emits `StorageGetEvent` when the Resource has been retrieved. */ abstract get(selector: S, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageGetEvent` when the Resource has been * retrieved. * * @default `true` */ emit?: boolean | null | undefined; }): Promise<{ resource: InstanceFor; metadata: MetadataFor; }>; /** * Get the metadata of a specific Resource. * * @param selector Selector of the Resource to get the metadata of. * @param opts Options for getting the metadata of the Resource. * * @returns Promise resolving the metadata of the Resource. * * @throws `ResourceNotFoundError` if the Resource was not found. * * @emits `StorageGetMetadataEvent` when the metadata of the Resource has * been retrieved. */ abstract getMetadata(selector: S, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageGetMetadataEvent` when the metadata of the * Resource has been retrieved. * * @default `true` */ emit?: boolean | null | undefined; }): Promise>; /** * Get the binary contents of a specific Resource. * * @param selector Selector of the Resource to get the contents of. * @param opts Options for getting the contents of the Resource. * * @returns Promise resolving the contents of the Resource. * * @throws `ResourceNotFoundError` if the Resource was not found. * * @emits `StorageGetContentsEvent` when the contents of the Resource have * been retrieved. */ abstract getContents(selector: Selector<'database' | 'snapshot' | 'branch'>, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageGetContentsEvent` when the contents of the * Resource have been retrieved. * * @default `true` */ emit?: boolean | null | undefined; }): Promise<{ contents: ByteStream; metadata: MetadataFor>; }>; /** * Set the binary contents of a specific Resource. * * @param selector Selector of the Resource to set the contents of. * @param contents Contents of the Resource. Either raw binary data or a * reference to another Resource. * @param opts Options for setting the contents of the Resource. * * @example ``` * // With contents from a `Uint8Array`. * const contents = await readFile('my-db.sqlite'); * await storage.setContents({ type: 'database', id: 'my-db' }, contents); * ``` * * @example ``` * // With contents from a `ByteStream`. * const contents = await streamFile('my-db.sqlite'); * await storage.setContents({ type: 'database', id: 'my-db' }, contents); * ``` * * @example ``` * // With contents from a `Selector`. * const source = new Selector({ type: 'database', id: 'source-db' }); * await storage.setContents({ type: 'database', id: 'my-db' }, source); * ``` * * @example ``` * // With contents from a `Resource`. * const source = await storage.create({ type: 'database', id: 'source-db' }, new Uint8Array(8192)); * await storage.setContents({ type: 'database', id: 'my-db' }, source); * ``` * * @returns Promise resolving once the contents of the Resource have been set. * * @throws `ResourceNotFoundError` if the Resource was not found. * @throws `InvalidBinaryContentsError` if the provided contents are invalid. * * @emits `StorageSetContentsEvent` when the contents of the Resource have * been set. */ abstract setContents(selector: Selector<'database' | 'snapshot' | 'branch'>, contents: ByteStream | Uint8Array | Selector<'database' | 'snapshot' | 'branch'>, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageSetContentsEvent` when the contents of * the Resource have been set. * * @default `true` */ emit?: boolean | null | undefined; }): Promise; /** * Free up any resources associated with a Resource. * * This method returns a Promise, allowing the `Storage` implementation to * perform any outstanding operations or synchronizations before the Resource * is marked as freed. * * @param selector Selector of the Resource to free. * @param opts Options for freeing the Resource. * * @returns Promise resolving once the Resource has been freed. * * @emits `StorageFreeEvent` when the Resource has been freed. */ abstract free(selector: Selector, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageFreeEvent` when the Resource has been * freed. * * @default `true` */ emit?: boolean | null | undefined; }): Promise; /** * Delete a specific Resource. * * @param selector Selector of the Resource to delete. * @param opts Options for deleting the Resource. * * @returns Promise resolving once the Resource has been deleted. * * @throws `ResourceNotFoundError` if the Resource was not found. * * @emits `StorageDeleteEvent` when the Resource has been deleted. */ abstract delete(selector: Selector, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `StorageDeleteEvent` when the Resource has been * deleted. * * @default `true` */ emit?: boolean | null | undefined; }): Promise; /** * Apply a Transaction to a specific Resource. * * @param selector Selector of the Resource to apply the Transaction to. * @param transaction Transaction to apply. * @param opts Options for applying the Transaction. * * @returns Promise resolving the results of the Transaction. * * @throws `ResourceNotFoundError` if the Resource was not found. * @throws `StatementPreparationError` if a Statement of the Transaction * could not be prepared. * @throws `StatementExecutionError` if a Statement of the Transaction * could not be executed. * * @emits `ResourceTransactionEvent` when the Transaction has been applied. */ abstract query = ReadonlyArray>(selector: Selector<'database' | 'snapshot' | 'branch'>, transaction: Transaction, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; /** * Whether to emit a `ResourceTransactionEvent` when the Resource has been * queried. * * @default `true` */ emit?: boolean | null | undefined; }): Promise>; } //#endregion //#region src/database.d.ts type DatabaseMetadata = { key: string; type: 'database' | 'snapshot' | 'branch'; parent: Selector['key'] | null; size: number; indexedAt: Date; createdAt: Date | null; modifiedAt: Date | null; }; type DatabaseConfig = Omit, 'type' | 'id'> & { /** * Type of the Database. * * Either `'database'`, `'snapshot'`, or `'branch'`. * * @default `'database'` */ type?: T | null | undefined; /** * Unique identifier of the Database within the scope of its parent. * * @default `crypto.randomUUID()` */ id?: string | null | undefined; /** * Parent of the Database. * * @default `null` */ parent?: Selector['key'] | Selector | null | undefined; /** * `Storage` instance to use for persisting the Database. * * If not set, the Database must be initialized by passing it to either * `hive.create()` or `hive.get()`. */ storage?: Storage | null | undefined; }; declare class Database extends Selector { /** * `Storage` instance to use for persisting the Database. * * If not set, the Database must be initialized by passing it to either * `hive.create()` or `hive.get()`. */ storage: Storage | null; constructor(config?: DatabaseConfig | null | undefined); /** * Get the metadata stored for the Database. * * @param opts Options for getting the metadata stored for the Database. * * @returns Promise resolving with the metadata stored for the Database. * * @throws `ResourceNotFoundError` if the Database was not found. * @throws `ResourceNotInitializedError` if the Database is not initialized. * To initialize the Database, pass it to either `hive.create()` or `hive.get()`. */ readonly getMetadata: (opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; }) => Promise; /** * Get the contents of the Database. * * @param opts Options for getting the contents of the Database. * * @returns Promise resolving with the contents of the Database. * * @throws `ResourceNotFoundError` if the Database was not found. * @throws `ResourceNotInitializedError` if the Database is not initialized. * To initialize the Database, pass it to either `hive.create()` or `hive.get()`. */ readonly getContents: (opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; }) => Promise<{ contents: ByteStream; metadata: DatabaseMetadata; }>; /** * Update the contents of the Database. * * @param contents Contents to store. * @param opts Options for storing the contents of the Database. * * @returns Promise resolving when the contents of the Database have been * stored. * * @throws `ResourceNotFoundError` if the Database was not found. * @throws `ResourceNotInitializedError` if the Database is not initialized. * To initialize the Database, pass it to either `hive.create()` or `hive.get()`. */ readonly setContents: (contents: ByteStream | Uint8Array | Selector<"database"> | Selector<"snapshot"> | Selector<"branch">, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; }) => Promise; /** * Apply a Transaction to the Database. * * @param input Transaction to apply to the Database. * @param opts Options for applying the Transaction to the Database. * * @returns Promise resolving the results of the Transaction. * * @throws `ResourceNotFoundError` if the Resource was not found. * @throws `StatementPreparationError` if a Statement of the Transaction * could not be prepared. * @throws `StatementExecutionError` if a Statement of the Transaction * could not be executed. * * @emits `ResourceTransactionEvent` when the Transaction has been applied. */ readonly query: = ReadonlyArray>(input: TransactionInput, opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; } | null | undefined) => Promise>; /** * Free the Database. * * @param opts Options for freeing the Database. * * @returns Promise resolving when the Database has been freed. * * @throws `ResourceNotFoundError` if the Database was not found. * @throws `ResourceNotInitializedError` if the Database is not initialized. * To initialize the Database, pass it to either `hive.create()` or `hive.get()`. */ readonly free: (opts?: { /** * Trace to associate the operation with. * * @default `null` */ trace?: Trace | null | undefined; }) => Promise; } //#endregion //#region src/selector.d.ts declare const RESOURCE_TYPES: readonly [{ readonly name: "namespace"; readonly abbreviation: "ns"; readonly path: "namespaces"; }, { readonly name: "database"; readonly abbreviation: "db"; readonly path: "databases"; }, { readonly name: "snapshot"; readonly abbreviation: "sn"; readonly path: "snapshots"; }, { readonly name: "branch"; readonly abbreviation: "br"; readonly path: "branches"; }]; /** * Regular expression used to validate the legitimacy of a key provided to a * `Selector` constructor. * * It validates if a key is both in the correct format and shape as well as the * following hierarchy: * * a) Only Namespaces and Databases can exist on the root level. * b) Namespaces can only have other Namespaces or Databases as children. * c) Databases can only have Snapshots or Branches as children. * d) Snapshots and Branches can both neither have any children. * * @example * ``` * const key = 'ns:my-namespace/ns:child-namespace/db:main/sn:snapshot-1'; * ``` * * @example * ``` * const key = 'ns:my-namespace/db:main/sn:snapshot-1'; * ``` * * @example * ``` * const key = 'db:main/br:branch-1'; * ``` */ declare const SELECTOR_KEY_REGEX: RegExp; /** * Regular expression used to extract the key of the parent of the Resource * addressed with the provided key. * * @example * ``` * const key = 'ns:my-namespace'; * * // parent: null * ``` * * @example * ``` * const key = 'ns:my-namespace/db:main'; * * // parent: 'ns:my-namespace' * ``` * * @example * ``` * const key = 'ns:my-namespace/db:main/sn:snapshot-1'; * * // parent: 'ns:my-namespace/db:main' * ``` */ declare const SELECTOR_PARENT_KEY_REGEX: RegExp; /** * Regular expression to extract the `type` and `id` of the Resource addressed * with the provided key. * * @example * ``` * const key = 'ns:my-namespace'; * * // type = 'ns' * // id = 'my-namespace' * ``` * * @example * ``` * const key = 'ns:my-namespace/db:main'; * * // type = 'db' * // id = 'main' * ``` * * @example * ``` * const key = 'ns:my-namespace/db:main/sn:snapshot-1'; * * // type = 'sn' * // id = 'snapshot-1' * ``` * */ declare const SELECTOR_DETAILS_REGEX: RegExp; type ResourceType = (typeof RESOURCE_TYPES)[number]['name']; type AbbreviatedResourceType = (typeof RESOURCE_TYPES)[number]['abbreviation']; type InstanceFor = S['type'] extends 'namespace' ? Namespace : S['type'] extends 'snapshot' ? Database<'snapshot'> : S['type'] extends 'branch' ? Database<'branch'> : Database<'database'>; type MetadataFor = S['type'] extends 'namespace' ? NamespaceMetadata : DatabaseMetadata; type SerializedMetadataFor = Omit & { indexedAt: string; createdAt: string | null; modifiedAt: string | null; }; declare const serializeMetadata: (metadata: MetadataFor) => SerializedMetadataFor; declare const deserializeMetadata: (metadata: SerializedMetadataFor) => MetadataFor; type SelectorInput = Selector['key'] | { type: T; id: string; parent?: Selector['key'] | Selector | null | undefined; }; declare class Selector { /** * Key of the Resource, containing its type, id and the key of a * potential parent Resource. * * @example * ``` * const db = new Selector({ type: 'database', id: 'main' }); * // => db:main * * const snapshot = new Selector({ type: 'snapshot', id: 'snapshot-1', parent: db }); * // => db:main/sn:snapshot-1 * * new Selector({ type: 'snapshot', id: 'nested-snapshot-1', parent: snapshot }); * // => db:main/sn:snapshot-1/sn:nested-snapshot-1 * * const branch = new Selector({ type: 'branch', id: 'branch-1', parent: db }); * // => db:main/br:branch-1 * * new Selector({ type: 'branch', id: 'nested-branch-1', parent: branch }); * // => db:main/br:branch-1/br:nested-branch-1 * ``` */ readonly key: string; private readonly cached; constructor(input: SelectorInput); get id(): string; get type(): T; get parent(): Selector | null; get name(): string; get path(): string; } export { IndexRefreshEvent as $, ResourceNotInitializedError as A, BadRequestError as B, Connection as C, Database as D, EventEmitter as E, FeatureNotImplementedError as F, SerializedErrorSchema as H, StatementExecutionError as J, KNOWN_ERRORS as K, StatementPreparationError as L, deserializeError as O, serializeError as P, BaseEvent as Q, ResourceTransactionEvent as R, Selector as S, UnexpectedErrorEvent as U, Storage as a, IndexStartEvent as a0, IndexStopEvent as a1, InstanceStartEvent as a2, InstanceStopEvent as a3, ResourceCloseEvent as a5, ResourceGetContentsEvent as a8, ResourceGetMetadataEvent as a9, StorageFreeEvent as aA, StorageGetEvent as aB, StorageHasEvent as aC, StorageListEvent as aD, StorageStartEvent as aE, StorageStopEvent as aF, Operation as aJ, RESOURCE_TYPES as aN, SELECTOR_DETAILS_REGEX as aP, SELECTOR_KEY_REGEX as aQ, SELECTOR_PARENT_KEY_REGEX as aR, deserializeMetadata as aT, serializeMetadata as aU, ResourceGetSizeEvent as aa, StorageCreateEvent as aw, Driver as b, Namespace as i, StorageDeleteEvent as k, ResourceSetContentsEvent as m, ExpiredCredentialsError as q, InvalidBinaryContentsError as r, InvalidCredentialsError as s, InvalidSelectorError as t, InvalidSelectorKeyError as u, MissingCredentialsError as v, NetworkError as w, ResourceExistsError as x, ResourceNotAccessibleError as y, ResourceNotFoundError as z }; export type { SerializedError as G, InstanceFor as I, MetadataFor as M, NamespaceMetadata as N, Trace as T, BaseEventConfig as V, EventType as W, HiveEventMap as X, HiveEventType as Y, IndexEventMap as Z, IndexEventType as _, Listener as a4, ResourceEventMap as a6, ResourceEventType as a7, UnexpectedErrorEventMap as aG, UnexpectedErrorEventType as aH, NamespaceConfig as aI, OperationConfig as aK, SerializedOperation as aL, AbbreviatedResourceType as aM, ResourceType as aO, SerializedMetadataFor as aS, SerializedBaseEvent as ab, SerializedHiveEvent as ac, SerializedIndexEvent as ad, SerializedIndexRefreshEvent as ae, SerializedIndexStartEvent as af, SerializedIndexStopEvent as ag, SerializedInstanceStartEvent as ah, SerializedInstanceStopEvent as ai, SerializedResourceCloseEvent as aj, SerializedResourceEvent as ak, SerializedResourceGetContentsEvent as al, SerializedResourceGetMetadataEvent as am, SerializedResourceGetSizeEvent as an, SerializedStorageCreateEvent as ao, SerializedStorageFreeEvent as ap, SerializedStorageGetEvent as aq, SerializedStorageHasEvent as ar, SerializedStorageListEvent as as, SerializedStorageStartEvent as at, SerializedStorageStopEvent as au, SerializedUnexpectedErrorEvent as av, StorageEvent as ax, StorageEventMap as ay, StorageEventType as az, DriverStartOptions as c, StorageStartOptions as d, CreateResourceOptions as e, DatabaseMetadata as f, SelectorInput as g, SerializedResourceTransactionEvent as h, EventMap as j, SerializedStorageDeleteEvent as l, SerializedResourceSetContentsEvent as n, Emitter as o, DatabaseConfig as p };