# Records and results

Client options, rows, metadata, and transport.

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

## DatabaseSchema


```ts
type DatabaseSchema = Record<string, object>;
```

## SchemaShape


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

## DefaultSchema


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

## RecordMetadata


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

## Row


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

## Insert


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

## RelayResult


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

## WriteReceipt


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

## ResultMeta


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

## Result


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

## TableDefinition


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

## TransportRead


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

## Transport


```ts
/** 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


```ts
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


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

## Session


```ts
interface Session {
  user: User;
}
```

## AuthChange


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

## ChangeEvent


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

## ChangePayload


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

## ChangeFilter


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

## ChannelStatus


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

## Signer


```ts
type Signer = ISigner;
```

## Selection


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

## Projection


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

## Cardinality


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

## QueryData


```ts
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


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

### Columns


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