Records and results

Read the errors and receipts guide. Signatures below come from the published SDK declarations. Access SDK services through db; use their constructors only when integrating at a lower level.

DatabaseSchema

type DatabaseSchema = Record<string, object>;

SchemaShape

type SchemaShape<DB> = {
  [K in keyof DB]: object;
};

DefaultSchema

type DefaultSchema = Record<string, Record<string, unknown>>;

RecordMetadata

interface RecordMetadata {
  pubkey: string;
  eventId: string;
  createdAt: number;
  updatedAt: number;
}

Row

type Row<T extends object> = T & {
  id: string;
  _nostr: RecordMetadata;
};

Insert

type Insert<T extends object> = T & {
  id?: string;
};

RelayResult

interface RelayResult {
  url: string;
  ok: boolean;
  message?: string;
}

WriteReceipt

interface WriteReceipt {
  id: string;
  eventId: string;
  relays: RelayResult[];
  queued?: boolean;
}

ResultMeta

interface ResultMeta {
  relays: RelayResult[];
  partial: boolean;
  receipts?: WriteReceipt[];
  nextCursor?: string;
  cached?: boolean;
  queued?: boolean;
}

Result

interface Result<T> {
  data: T | null;
  error: NostrbaseError | null;
  count?: number;
  meta?: ResultMeta;
}

TableDefinition

interface TableDefinition<T extends object> {
  indexes?: readonly (keyof T & string)[];
  validate?: (data: unknown) => data is T;
}

TransportRead

interface TransportRead {
  events: NostrEvent[];
  relays: RelayResult[];
}

Transport

/** Implement this interface to use a custom transport. Incoming events are verified by the SDK. */
interface Transport {
  request(
    relays: string[],
    filters: Filter[],
    options: {
      timeout: number;
      signal: AbortSignal;
    },
  ): Promise<TransportRead>;
  publish(
    relays: string[],
    event: NostrEvent,
    options: {
      timeout: number;
      signal: AbortSignal;
    },
  ): Promise<RelayResult[]>;
  subscribe(relays: string[], filters: Filter[]): Observable<NostrEvent>;
}

ClientOptions

interface ClientOptions<DB extends SchemaShape<DB>> {
  /** A stable application namespace. It is part of every record address. */
  namespace: string;
  relays: readonly string[];
  signer?: ISigner;
  schema?: {
    [K in keyof DB]: TableDefinition<DB[K]>;
  };
  timeout?: number;
  /** Minimum relay acknowledgements required for a successful write (default: 1). */
  minWriteAcks?: number;
  pool?: RelayPool;
  eventStore?: EventStore;
  relayOptions?: RelayOptions;
  transport?: Transport;
  persistence?: PersistenceOptions;
  offline?: OfflineOptions;
  sync?: SyncOptions;
  storage?: StorageOptions;
  diagnostics?: DiagnosticsOptions;
  groups?: GroupsOptions;
}

User

interface User {
  id: string;
  pubkey: string;
}

Session

interface Session {
  user: User;
}

AuthChange

type AuthChange = "INITIAL_SESSION" | "SIGNED_IN" | "SIGNED_OUT";

ChangeEvent

type ChangeEvent = "INSERT" | "UPDATE" | "DELETE";

ChangePayload

interface ChangePayload<T extends object> {
  eventType: ChangeEvent;
  table: string;
  new: Row<T> | null;
  old: Row<T> | null;
  event: NostrEvent;
}

ChangeFilter

interface ChangeFilter {
  table: string;
  event?: ChangeEvent | "*";
  author?: string /** Supabase-style equality: "done=eq.false". */;
  filter?: string;
}

ChannelStatus

type ChannelStatus = "SUBSCRIBED" | "CHANNEL_ERROR" | "CLOSED";

Signer

type Signer = ISigner;

Selection

type Selection<T, C extends string> = string extends C
  ? C
  : C extends "*"
    ? C
    : Exclude<Columns<C>, keyof T> extends never
      ? C
      : never;

Projection

type Projection<T, C extends string> = C extends "*"
  ? T
  : string extends C
    ? Partial<T>
    : Pick<T, Extract<Columns<C>, keyof T>>;

Cardinality

type Cardinality = "many" | "one" | "maybe";

QueryData

type QueryData<T, C extends Cardinality> = C extends "many"
  ? T[]
  : C extends "one"
    ? T
    : T | null;

Supporting declarations

These types appear in public signatures but are not package exports.

Trim

type Trim<S extends string> = S extends ` ${infer R}`
  ? Trim<R>
  : S extends `${infer R} `
    ? Trim<R>
    : S;

Columns

type Columns<S extends string> = S extends `${infer L},${infer R}`
  ? Trim<L> | Columns<R>
  : Trim<S>;