Query builder

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

SelectOptions

interface SelectOptions {
  count?: "exact";
  head?: boolean;
}

QueryBuilder

/** Queries are immutable and execute once when awaited. */
declare class QueryBuilder<
  T extends object,
  Selected = Row<T>,
  C extends Cardinality = "many",
> implements PromiseLike<Result<QueryData<Selected, C>>> {}

Properties

readonly table: string;

constructor

constructor(
  host: QueryHost,
  table: string,
  state?: QueryState,
  columns?: string,
  cardinality?: Cardinality,
  throws?: boolean,
);

inGroup

/** Route this query to a shared private collection. Unsupported hosts never fall back to another scope. */
inGroup(groupId: string): QueryBuilder<T, Selected, C>;

select

select<const Columns extends string = "*">(
  columns?: Columns & Selection<Row<T>, Columns>,
  options?: SelectOptions,
): QueryBuilder<T, Projection<Row<T>, Columns>, C>;

insert

insert(values: Insert<T> | Insert<T>[]): QueryBuilder<T, Row<T>, "many">;

upsert

upsert(values: Insert<T> | Insert<T>[]): QueryBuilder<T, Row<T>, "many">;

update

update(patch: Partial<T>): QueryBuilder<T, Row<T>, "many">;

delete

delete(): QueryBuilder<T, Row<T>, "many">;

eq

eq<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

eq<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;

neq

neq<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

neq<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;

in

in<K extends QueryField<Row<T>>>(
  field: K,
  values: readonly QueryFieldValue<Row<T>, K>[],
): QueryBuilder<T, Selected, C>;

gt

gt<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

gt<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;

gte

gte<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

gte<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;

lt

lt<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

lt<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;

lte

lte<K extends keyof Row<T> & string>(
  field: K,
  value: Row<T>[K],
): QueryBuilder<T, Selected, C>;

lte<K extends Exclude<QueryField<Row<T>>, keyof Row<T>>>(
  field: K,
  value: QueryFieldValue<Row<T>, K>,
): QueryBuilder<T, Selected, C>;

is

is<K extends QueryField<Row<T>>>(
  field: K,
  value: null | boolean,
): QueryBuilder<T, Selected, C>;

contains

contains<K extends QueryField<Row<T>>>(
  field: K,
  value: DeepPartial<QueryFieldValue<Row<T>, K>>,
): QueryBuilder<T, Selected, C>;

containedBy

containedBy<K extends QueryField<Row<T>>>(
  field: K,
  value: DeepPartial<QueryFieldValue<Row<T>, K>>,
): QueryBuilder<T, Selected, C>;

overlaps

overlaps<K extends QueryField<Row<T>>>(
  field: K,
  value: FilterValue<QueryFieldValue<Row<T>, K>, "overlaps">,
): QueryBuilder<T, Selected, C>;

like

like<K extends QueryField<Row<T>>>(
  field: K,
  pattern: string,
): QueryBuilder<T, Selected, C>;

ilike

ilike<K extends QueryField<Row<T>>>(
  field: K,
  pattern: string,
): QueryBuilder<T, Selected, C>;

textSearch

textSearch<K extends QueryField<T>>(
  field: K,
  query: string,
): QueryBuilder<T, Selected, C>;

filter

filter<K extends QueryField<Row<T>>, O extends FilterOperator>(
  field: K,
  op: O,
  value: FilterValue<QueryFieldValue<Row<T>, K>, O> | string,
): QueryBuilder<T, Selected, C>;

not

not<K extends QueryField<Row<T>>, O extends FilterOperator>(
  field: K,
  op: O,
  value: FilterValue<QueryFieldValue<Row<T>, K>, O> | string,
): QueryBuilder<T, Selected, C>;

or

/** PostgREST-style alternatives. Other chained filters remain AND conditions. */
or(expression: string): QueryBuilder<T, Selected, C>;

local

/** Read only from the local verified cache; no relay request is made. */
local(): QueryBuilder<T, Selected, C>;

queue

/** Sign and save a mutation for explicit offline replay. Requires a signed-in author. */
queue(): QueryBuilder<T, Selected, C>;

page

/** Timestamp/event-id cursor pagination, newest records first. */
page(
  size: number,
  options?: {
    cursor?: string;
  },
): QueryBuilder<T, Selected, C>;

match

match(values: Partial<Row<T>>): QueryBuilder<T, Selected, C>;

author

author(pubkey: string | readonly string[]): QueryBuilder<T, Selected, C>;

order

order(
  field: QueryField<Row<T>>,
  options?: {
    ascending?: boolean;
    nullsFirst?: boolean;
  },
): QueryBuilder<T, Selected, C>;

limit

limit(count: number): QueryBuilder<T, Selected, C>;

range

range(from: number, to: number): QueryBuilder<T, Selected, C>;

all

/** Explicitly permit an update or delete of every record owned by the signer. */
all(): QueryBuilder<T, Selected, C>;

single

single(): QueryBuilder<T, Selected, "one">;

maybeSingle

maybeSingle(): QueryBuilder<T, Selected, "maybe">;

abortSignal

abortSignal(signal: AbortSignal): QueryBuilder<T, Selected, C>;

throwOnError

throwOnError(): QueryBuilder<T, Selected, C>;

then

then<TResult1 = Result<QueryData<Selected, C>>, TResult2 = never>(
  onfulfilled?:
    | ((value: Result<QueryData<Selected, C>>) => TResult1 | PromiseLike<TResult1>)
    | null,
  onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
): Promise<TResult1 | TResult2>;

Supporting declarations

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

QueryState

interface QueryState {
  operation: "select" | "insert" | "upsert" | "update" | "delete";
  groupId?: string;
  values?: object[];
  patch?: object;
  predicates: Predicate[];
  authors?: string[];
  order: {
    field: string;
    ascending: boolean;
    nullsFirst?: boolean;
  }[];
  count?: "exact";
  head?: boolean;
  limit?: number;
  range?: [number, number];
  allowAll: boolean;
  returning: boolean;
  signal?: AbortSignal;
  validationError?: NostrbaseError;
  queue?: boolean;
  local?: boolean;
  page?: {
    size: number;
    cursor?: string;
  };
}

QueryHost

interface QueryHost {
  execute<T extends object>(
    table: string,
    state: QueryState,
  ): Promise<Result<Row<T>[]>>;
  executeInGroup?<T extends object>(
    groupId: string,
    table: string,
    state: QueryState,
  ): Promise<Result<Row<T>[]>>;
}