Skip to content

valkeyrie


valkeyrie / Valkeyrie

Class: Valkeyrie<TRegistry> ​

Defined in: valkeyrie.ts:113

Valkeyrie database instance with optional schema registry type tracking.

Type Parameters ​

TRegistry ​

TRegistry extends SchemaRegistryType = readonly []

Compile-time schema registry for automatic type inference

Accessors ​

[kSchemaRegistry] ​

Get Signature ​

ts
get kSchemaRegistry: SchemaRegistry | undefined;

Defined in: valkeyrie.ts:1277

Internal symbol-based accessor for schema registry. Used by AtomicOperation for validation.

Returns ​

SchemaRegistry | undefined

Methods ​

commitVersionstamp() ​

ts
commitVersionstamp(): symbol;

Defined in: valkeyrie.ts:137

Returns ​

symbol


withSchema() ​

ts
static withSchema<TPattern, TSchema>(pattern: TPattern, schema: TSchema): ValkeyrieBuilder<readonly [readonly [TPattern, TSchema] extends SchemaRegistryEntry ? SchemaRegistryEntry & readonly [TPattern, TSchema] : never]>;

Defined in: valkeyrie.ts:149

Creates a builder for registering schemas before opening the database. Uses const type parameter to automatically infer literal types without as const.

Type Parameters ​

TPattern ​

TPattern extends Key

TSchema ​

TSchema extends StandardSchemaV1<unknown, unknown>

Parameters ​

pattern ​

TPattern

Key pattern with optional '*' wildcards

schema ​

TSchema

Standard schema for validation

Returns ​

ValkeyrieBuilder<readonly [readonly [TPattern, TSchema] extends SchemaRegistryEntry ? SchemaRegistryEntry & readonly [TPattern, TSchema] : never]>

A builder instance for chaining with type tracking


open() ​

Call Signature ​

ts
static open(path?: string, options?: {
  serializer?: () => Serializer;
  destroyOnClose?: boolean;
}): Promise<Valkeyrie<readonly []>>;

Defined in: valkeyrie.ts:177

Opens a new Valkeyrie database instance.

Accepts either a file path for the built-in SQLite backend, or a DriverFactory to supply a custom storage backend. Omit the argument for an in-memory SQLite database.

Parameters ​
path? ​

string

Optional path to the database file (defaults to in-memory)

options? ​

Optional configuration options

serializer? ​

() => Serializer

destroyOnClose? ​

boolean

Returns ​

Promise<Valkeyrie<readonly []>>

A new Valkeyrie instance

Example ​
typescript
// Built-in SQLite (in-memory or file path)
const memory = await Valkeyrie.open()
const file = await Valkeyrie.open('./data.db')

// Custom backend: `createMyDriver` returns an object implementing Driver
const custom = await Valkeyrie.open(async (serializer) => createMyDriver(serializer))

Call Signature ​

ts
static open(driverFn: DriverFactory, options?: {
  serializer?: () => Serializer;
  destroyOnClose?: boolean;
}): Promise<Valkeyrie<readonly []>>;

Defined in: valkeyrie.ts:191

Opens a new Valkeyrie database instance backed by a custom driver.

Parameters ​
driverFn ​

DriverFactory

Function that creates the driver, optionally using the serializer

options? ​

Optional configuration options

serializer? ​

() => Serializer

destroyOnClose? ​

boolean

Returns ​

Promise<Valkeyrie<readonly []>>

A new Valkeyrie instance


[kOpen]() ​

ts
static [kOpen](
   driverFn: DriverFactory, 
   options: {
  serializer?: () => Serializer;
  destroyOnClose?: boolean;
}, 
schemaRegistry?: SchemaRegistry): Promise<Valkeyrie<readonly []>>;

Defined in: valkeyrie.ts:216

Internal method to open a database with schemas. Used by ValkeyrieBuilder.

Parameters ​

driverFn ​

DriverFactory

options ​
serializer? ​

() => Serializer

destroyOnClose? ​

boolean

schemaRegistry? ​

SchemaRegistry

Returns ​

Promise<Valkeyrie<readonly []>>


from() ​

ts
static from<T>(iterable: Iterable<T>, options: FromOptions<T>): Promise<Valkeyrie<readonly []>>;

Defined in: valkeyrie.ts:294

Creates and populates a Valkeyrie database from a synchronous iterable.

Type Parameters ​

T ​

T

Parameters ​

iterable ​

Iterable<T>

The iterable to populate the database from

options ​

FromOptions<T>

Configuration options including prefix and key extraction

Returns ​

Promise<Valkeyrie<readonly []>>

A populated Valkeyrie instance

Example ​

typescript
const users = [
  { id: 1, name: 'Alice' },
  { id: 2, name: 'Bob' }
]
const db = await Valkeyrie.from(users, {
  prefix: ['users'],
  keyProperty: 'id'
})

[kFrom]() ​

ts
static [kFrom]<T>(
   iterable: Iterable<T>, 
   options: FromOptions<T>, 
schemaRegistry?: SchemaRegistry): Promise<Valkeyrie<readonly []>>;

Defined in: valkeyrie.ts:305

Internal method to create and populate a database with schemas. Used by ValkeyrieBuilder.

Type Parameters ​

T ​

T

Parameters ​

iterable ​

Iterable<T>

options ​

FromOptions<T>

schemaRegistry? ​

SchemaRegistry

Returns ​

Promise<Valkeyrie<readonly []>>


fromAsync() ​

ts
static fromAsync<T>(iterable: AsyncIterable<T>, options: FromOptions<T>): Promise<Valkeyrie<readonly []>>;

Defined in: valkeyrie.ts:428

Creates and populates a Valkeyrie database from an asynchronous iterable.

Type Parameters ​

T ​

T

Parameters ​

iterable ​

AsyncIterable<T>

The async iterable to populate the database from

options ​

FromOptions<T>

Configuration options including prefix and key extraction

Returns ​

Promise<Valkeyrie<readonly []>>

A populated Valkeyrie instance

Example ​

typescript
async function* generateUsers() {
  yield { id: 1, name: 'Alice' }
  yield { id: 2, name: 'Bob' }
}

const db = await Valkeyrie.fromAsync(generateUsers(), {
  prefix: ['users'],
  keyProperty: 'id'
})

[kFromAsync]() ​

ts
static [kFromAsync]<T>(
   iterable: AsyncIterable<T>, 
   options: FromOptions<T>, 
schemaRegistry?: SchemaRegistry): Promise<Valkeyrie<readonly []>>;

Defined in: valkeyrie.ts:439

Internal method to create and populate a database with schemas from async iterable. Used by ValkeyrieBuilder.

Type Parameters ​

T ​

T

Parameters ​

iterable ​

AsyncIterable<T>

options ​

FromOptions<T>

schemaRegistry? ​

SchemaRegistry

Returns ​

Promise<Valkeyrie<readonly []>>


close() ​

ts
close(): Promise<void>;

Defined in: valkeyrie.ts:543

Returns ​

Promise<void>


destroy() ​

ts
destroy(): Promise<void>;

Defined in: valkeyrie.ts:570

Destroys the database by removing the underlying database file. This operation cannot be undone and will result in permanent data loss.

Returns ​

Promise<void>

A promise that resolves when the database has been destroyed


clear() ​

ts
clear(): Promise<void>;

Defined in: valkeyrie.ts:579

Clears all data from the database but keeps the database file. This operation cannot be undone and will result in permanent data loss.

Returns ​

Promise<void>

A promise that resolves when the database has been cleared


validateKeys() ​

ts
validateKeys(keys: unknown[]): asserts keys is Key[];

Defined in: valkeyrie.ts:590

Validates that the provided keys are arrays.

Parameters ​

keys ​

unknown[]

The keys to validate.

Returns ​

asserts keys is Key[]

Throws ​

If any key is not an array.


get() ​

ts
get<TKey>(key: TKey): Promise<EntryMaybe<InferTypeForKey<TRegistry, TKey>>>;

Defined in: valkeyrie.ts:827

Gets a value from the database with automatic type inference based on registered schemas. Uses const type parameter to automatically infer literal key types without as const.

Type Parameters ​

TKey ​

TKey extends Key

Parameters ​

key ​

TKey

The key to retrieve (supports literal type inference)

Returns ​

Promise<EntryMaybe<InferTypeForKey<TRegistry, TKey>>>

Entry with the value or null if not found. Type is automatically inferred from schema registry.


getMany() ​

ts
getMany<T>(keys: Key[]): Promise<EntryMaybe<T>[]>;

Defined in: valkeyrie.ts:857

Gets multiple values from the database. Note: For type inference, use individual get() calls instead.

Type Parameters ​

T ​

T = unknown

Parameters ​

keys ​

Key[]

Array of keys to retrieve

Returns ​

Promise<EntryMaybe<T>[]>

Array of entries with values or nulls


set() ​

ts
set<TKey>(
   key: TKey, 
   value: InferTypeForKey<TRegistry, TKey>, 
   options: SetOptions): Promise<{
  ok: true;
  versionstamp: string;
}>;

Defined in: valkeyrie.ts:877

Sets a value in the database with automatic type checking based on registered schemas. Uses const type parameter to automatically infer literal key types without as const.

Type Parameters ​

TKey ​

TKey extends Key

Parameters ​

key ​

TKey

The key to set (supports literal type inference)

value ​

InferTypeForKey<TRegistry, TKey>

The value to set. Type is automatically checked against schema registry.

options ​

SetOptions = {}

Optional settings like expireIn

Returns ​

Promise<{ ok: true; versionstamp: string; }>

Result with versionstamp


delete() ​

ts
delete(key: Key): Promise<void>;

Defined in: valkeyrie.ts:907

Parameters ​

key ​

Key

Returns ​

Promise<void>


list() ​

Call Signature ​

ts
list<TPrefix>(selector: 
  | {
  prefix: TPrefix;
}
  | {
  prefix: TPrefix;
  start: Key;
}
  | {
  prefix: TPrefix;
  end: Key;
}, options?: ListOptions): AsyncIterableIterator<Entry<InferTypeForPrefix<TRegistry, TPrefix>>, void, any> & {
  cursor: string;
  [asyncDispose]: Promise<void>;
};

Defined in: valkeyrie.ts:1156

Type Parameters ​
TPrefix ​

TPrefix extends Key

Parameters ​
selector ​

{ prefix: TPrefix; } | { prefix: TPrefix; start: Key; } | { prefix: TPrefix; end: Key; }

options? ​

ListOptions

Returns ​

AsyncIterableIterator<Entry<InferTypeForPrefix<TRegistry, TPrefix>>, void, any> & { cursor: string; [asyncDispose]: Promise<void>; }

Call Signature ​

ts
list<T>(selector: {
  start: Key;
  end: Key;
}, options?: ListOptions): AsyncIterableIterator<Entry<T>, void, any> & {
  cursor: string;
  [asyncDispose]: Promise<void>;
};

Defined in: valkeyrie.ts:1170

Type Parameters ​
T ​

T = unknown

Parameters ​
selector ​
start ​

Key

end ​

Key

options? ​

ListOptions

Returns ​

AsyncIterableIterator<Entry<T>, void, any> & { cursor: string; [asyncDispose]: Promise<void>; }


cleanup() ​

ts
cleanup(): Promise<void>;

Defined in: valkeyrie.ts:1262

Returns ​

Promise<void>


atomic() ​

ts
atomic(): AtomicOperation<TRegistry>;

Defined in: valkeyrie.ts:1268

Returns ​

AtomicOperation<TRegistry>


executeAtomicOperation() ​

ts
executeAtomicOperation(checks: Check[], mutations: Mutation<unknown>[]): Promise<
  | {
  ok: true;
  versionstamp: string;
}
  | {
  ok: false;
}>;

Defined in: valkeyrie.ts:1281

Parameters ​

checks ​

Check[]

mutations ​

Mutation<unknown>[]

Returns ​

Promise< | { ok: true; versionstamp: string; } | { ok: false; }>


[dispose]() ​

ts
dispose: void;

Defined in: valkeyrie.ts:1368

Returns ​

void


[asyncDispose]() ​

ts
asyncDispose: Promise<void>;

Defined in: valkeyrie.ts:1372

Returns ​

Promise<void>


watch() ​

ts
watch<TKeys>(keys: [...TKeys[]]): ReadableStream<{ [K in string | number | symbol]: TKeys[K<K>] extends Key ? EntryMaybe<InferTypeForKey<TRegistry, any[any]>> : never }>;

Defined in: valkeyrie.ts:1389

Watches multiple keys for changes with automatic type inference based on registered schemas. Uses const type parameter to automatically infer literal key types without as const.

Type Parameters ​

TKeys ​

TKeys extends readonly Key[]

Parameters ​

keys ​

[...TKeys[]]

Array of keys to watch (supports literal type inference)

Returns ​

ReadableStream<{ [K in string | number | symbol]: TKeys[K<K>] extends Key ? EntryMaybe<InferTypeForKey<TRegistry, any[any]>> : never }>

ReadableStream of entry arrays. Types are automatically inferred from schema registry.

Released under the MIT License.