TypeScript Types
The SDK provides comprehensive TypeScript type definitions for type-safe development. This page documents the key types and interfaces used throughout the SDK.
Connection Types
ConnectionStatus
Represents the current connection state.
type ConnectionStatus = "disconnected" | "connecting" | "reconnecting" | "connected"
Example:
if (db.status === "connected") {
console.log('Ready to execute queries');
}
DriverOptions
Configuration options for the Surreal driver.
interface DriverOptions {
engines?: Engines;
codecs?: Codecs;
codecOptions?: CodecOptions;
websocketImpl?: typeof WebSocket;
fetchImpl?: typeof fetch;
}
Properties:
engines - Custom engine factories for different protocolscodecs - Custom codec factories for encoding/decodingcodecOptions - Options for codec behaviorwebsocketImpl - Custom WebSocket implementationfetchImpl - Custom fetch implementation
Example:
const db = new Surreal({
codecOptions: {
useNativeDates: true
}
});
ConnectOptions
Options for establishing a connection.
interface ConnectOptions {
namespace?: string;
database?: string;
authentication?: AuthProvider;
versionCheck?: boolean;
invalidateOnExpiry?: boolean;
reconnect?: boolean | Partial<ReconnectOptions>;
}
Properties:
namespace - Namespace to usedatabase - Database to useauthentication - Authentication details or provider functionversionCheck - Enable version compatibility checking (default: true)invalidateOnExpiry - Invalidate session on token expiry (default: false)reconnect - Reconnection behavior configuration (default: true)
Example:
await db.connect('ws://localhost:8000', {
namespace: 'my_namespace',
database: 'my_database',
authentication: {
username: 'root',
password: 'root'
},
reconnect: {
attempts: 10,
retryDelay: 1000
}
});
ReconnectOptions
Configuration for automatic reconnection behavior.
interface ReconnectOptions {
enabled: boolean;
attempts: number;
retryDelay: number;
retryDelayMax: number;
retryDelayMultiplier: number;
retryDelayJitter: number;
catch?: (error: Error) => boolean;
}
Properties:
enabled - Enable automatic reconnectionattempts - Maximum reconnection attempts (-1 for unlimited)retryDelay - Initial delay before reconnecting (ms)retryDelayMax - Maximum delay between attempts (ms)retryDelayMultiplier - Multiply delay after each failed attemptretryDelayJitter - Random offset percentage for delayscatch - Custom error handler for reconnection errors
VersionInfo
SurrealDB version information.
interface VersionInfo {
version: string;
}
Example:
const info = await db.version();
console.log(info.version);
Authentication Types
AnyAuth
Union type for all authentication methods.
type AnyAuth =
| SystemAuth
| NamespaceAuth
| DatabaseAuth
| AccessRecordAuth
SystemAuth
System user authentication (root, namespace, or database level).
interface SystemAuth {
username: string;
password: string;
}
Example:
await db.signin({
username: 'root',
password: 'root'
});
AccessRecordAuth
Record user authentication via access methods.
interface AccessRecordAuth {
namespace: string;
database: string;
access: string;
variables?: Record<string, unknown>;
}
Example:
await db.signup({
namespace: 'my_namespace',
database: 'my_database',
access: 'user_access',
variables: {
email: 'user@example.com',
password: 'password123'
}
});
Tokens
Authentication token pair.
interface Tokens {
access: string;
refresh?: string;
}
Example:
const tokens = await db.signin(credentials);
console.log(tokens.access);
console.log(tokens.refresh);
AuthProvider
Function or static value for providing authentication.
type AuthProvider =
| AnyAuth
| (() => AnyAuth | Promise<AnyAuth>)
Example:
await db.connect('ws://localhost:8000', {
authentication: async () => ({
username: await getUsername(),
password: await getPassword()
})
});
Session Types
Session
Session identifier type.
type Session = Uuid | undefined
NamespaceDatabase
Namespace and database pair.
interface NamespaceDatabase {
namespace?: string;
database?: string;
}
Example:
await db.use({
namespace: 'production',
database: 'main'
});
SessionEvents
Events emitted by sessions.
type SessionEvents = {
auth: [Tokens | null];
using: [NamespaceDatabase];
}
SurrealEvents
Events emitted by Surreal instances.
type SurrealEvents = SessionEvents & {
connecting: [];
connected: [string];
reconnecting: [];
disconnected: [];
error: [Error];
}
Query Types
RecordResult<T>
Ensures records have an id field of type RecordId.
type RecordResult<T> = T extends object
? { id: RecordId } & T
: { id: RecordId }
Example:
interface User {
name: string;
email: string;
}
const user: RecordResult<User> = await db.select(new RecordId('users', 'john'));
console.log(user.id);
console.log(user.name);
QueryResponse<T>
Response from a query execution.
type QueryResponse<T = unknown> =
| QueryResponseSuccess<T>
| QueryResponseFailure
interface QueryResponseSuccess<T> {
success: true;
stats?: QueryStats;
type: "live" | "kill" | "other";
result: T;
}
interface QueryResponseFailure {
success: false;
stats?: QueryStats;
error: {
code: number;
message: string;
};
}
Example:
const responses = await db.query('SELECT * FROM users').responses();
for (const response of responses) {
if (response.success) {
console.log('Result:', response.result);
} else {
console.error('Error:', response.error.message);
}
}
QueryStats
Query execution statistics.
interface QueryStats {
recordsReceived: number;
bytesReceived: number;
recordsScanned: number;
bytesScanned: number;
duration: Duration;
}
LiveResource
Resources that can be subscribed to with live queries.
type LiveResource = Table | RecordId | RecordIdRange
LiveMessage
Message received from a live query subscription.
interface LiveMessage<T = unknown> {
action: "CREATE" | "UPDATE" | "DELETE";
result: T;
diff?: unknown;
}
Example:
for await (const message of subscription) {
console.log(`${message.action}:`, message.result);
}
Value Types
RecordIdValue
Valid types for record ID components.
type RecordIdValue =
| string
| number
| Uuid
| bigint
| unknown[]
| Record<string, unknown>
Values<T>
Extract values from a type, excluding id field.
type Values<T> = Omit<T, 'id'>
Example:
interface User {
id: RecordId;
name: string;
email: string;
}
const userData: Values<User> = {
name: 'John',
email: 'john@example.com'
};
Nullable<T>
Make properties nullable.
type Nullable<T> = {
[K in keyof T]: T[K] | null;
}
Codec Types
CodecOptions
Options for value encoding/decoding.
interface CodecOptions {
useNativeDates?: boolean;
valueEncodeVisitor?: (value: unknown) => unknown;
valueDecodeVisitor?: (value: unknown) => unknown;
}
Properties:
useNativeDates - Use native Date objects instead of DateTime (loses nanosecond precision)valueEncodeVisitor - Custom function to transform values before encodingvalueDecodeVisitor - Custom function to transform values after decoding
Example:
const db = new Surreal({
codecOptions: {
useNativeDates: true,
valueDecodeVisitor: (value) => {
return value;
}
}
});
Export/Import Types
SqlExportOptions
Options for database export.
interface SqlExportOptions {
users: boolean;
accesses: boolean;
params: boolean;
functions: boolean;
analyzers: boolean;
tables: boolean | string[];
versions: boolean;
records: boolean;
sequences: boolean;
v3: boolean;
}
The v3 option controls whether to include v3-specific export content.
Example:
const sql = await db.export({
tables: ['users', 'posts'],
records: true,
functions: false
});
Utility Types
Prettify<T>
Expand type for better IDE display.
type Prettify<T> = { [K in keyof T]: T[K] } & {}
EventPublisher<T>
Interface for event subscription.
interface EventPublisher<T extends Record<string, unknown[]>> {
subscribe<K extends keyof T>(
event: K,
listener: (...payload: T[K]) => void
): () => void;
}
ApiRequest<T>
Request options for user-defined API endpoints.
interface ApiRequest<T = unknown> {
body?: T;
method?: string;
headers?: Record<string, string>;
query?: Record<string, string>;
}
Properties:
body - Request body to sendmethod - HTTP method (default: "get")headers - Additional headers for the requestquery - Query parameters to append to the URL
Example:
const api = db.api();
const result = await api.invoke('/custom', {
method: 'post',
body: { data: 'value' },
headers: { 'X-Custom': 'header' },
query: { filter: 'active' }
});
Best Practices
1. Use Generic Type Parameters
Leverage generics for type-safe operations:
interface User {
name: string;
email: string;
}
const users = await db.select<User>(new Table('users'));
users[0].name;
2. Define Custom Types
Create types for your data models:
interface Post {
title: string;
content: string;
author: RecordId<'users'>;
created_at: DateTime;
}
const posts = await db.select<Post>(new Table('posts'));
3. Use Type Guards
Implement type guards for runtime type checking:
function isUser(value: unknown): value is User {
return (
typeof value === 'object' &&
value !== null &&
'name' in value &&
'email' in value
);
}
if (isUser(data)) {
console.log(data.email);
}
4. Handle Union Types
Properly handle discriminated unions:
const response = await db.query('SELECT * FROM users').responses();
for (const r of response) {
if (r.success) {
console.log(r.result);
} else {
console.error(r.error);
}
}
See Also
Source: types/
