SDK 레퍼런스

createNaru(options?: { site?: string }): NaruClient

interface Admin extends SiteCode, LiveQueries

• media: {
    upload(
      file: Blob | File,
      options?: {
        onProgress?: (
          progress:
            | { phase: "preparing" }
            | { loaded: number; phase: "uploading"; total: number }
            | { phase: "finishing" },
        ) => void;
        signal?: AbortSignal;
      },
    ): Promise<{
      contentType: string;
      id: string;
      name: string;
      size: number;
      url: string;
    }>;
  }

• batch(
    writes: readonly (
      | {
          collection: string;
          set: { condition?: WriteCondition; data: unknown; id: string };
        }
      | {
          collection: string;
          delete: { condition?: { revision: Revision }; id: string };
        }
    )[],
    options?: { signal?: AbortSignal },
  ): Promise<
    ({
      createdAt: string;
      id: string;
      revision: Revision;
      updatedAt: string;
    } | null)[]
  >

  Commits every write or none. Conditions guard individual documents. Does not retry. Resolves, in the order written, with what each set stored and null for each delete.

• collection<T = Json>(name: string): AdminCollection<T>

• signOut(): Promise<void>

  This handle stops working at once, even if the revoke request fails.

interface AdminCollection<T = Json> extends PublicCollection<T>

• delete(
    id: string,
    options?: { condition?: { revision: Revision }; signal?: AbortSignal },
  ): Promise<void>

  Deleting a missing document succeeds unless a condition was supplied.

• set(
    id: string,
    data: T,
    options?: { condition?: WriteCondition; signal?: AbortSignal },
  ): Promise<Document<T>>

  Replaces the whole document or creates it.

interface Document<T = Json>

• createdAt: string

• data: T

• id: string

• revision: Revision

• updatedAt: string

interface ListOptions

• after?: string | null

  Opaque cursor returned by the preceding page.

• filter?: Filter

• includeTotal?: boolean

• signal?: AbortSignal

• size?: number

  Default 50; maximum 100.

• sort?: Sort

interface Live

• close(): void

interface LiveQueries

• subscribe<R = Json>(
    name: string,
    args: Json | undefined,
    onResult: (result: R) => void,
    options?: { onError(error: NaruError): void },
  ): Live

  Runs "<module/path>:<query>" from the site's _naru/queries/ as query() does, calls onResult with its answer, and again whenever a write changes a table it read and the answer with it, until closed. After the connection drops it is asked again, so the latest answer arrives once it is back. A failure, now or later, goes to onError. A connection holds at most 20. args left undefined is null, as query()'s are.

interface Member extends SiteCode, LiveQueries

• id: string

  This member's ID on this site, the same on every visit: ctx.member.id in the site's queries and mutations. It is not their Naru account name.

• media: {
    upload(
      file: Blob | File,
      options?: {
        onProgress?: (
          progress:
            | { phase: "preparing" }
            | { loaded: number; phase: "uploading"; total: number }
            | { phase: "finishing" },
        ) => void;
        signal?: AbortSignal;
      },
    ): Promise<{
      contentType: string;
      id: string;
      name: string;
      size: number;
      url: string;
    }>;
  }

• signOut(): Promise<void>

  Signs out on every page of this site. This handle stops working at once, even if the revoke request fails.

interface NaruClient extends SiteCode, LiveQueries

• auth: {
    session(): Promise<Admin | null>;
    signIn(options?: { collections?: readonly string[] }): Promise<void>;
  }

• members: { session(): Promise<Member | null>; signIn(): Promise<void> }

• collection<T = Json>(name: string): PublicCollection<T>

  Visitor access, even when signed in.

interface Page<T = Json>

• documents: Document<T>[]

• nextCursor: string | null

• totalCount?: number

interface PublicCollection<T = Json>

• add(data: T, options?: { signal?: AbortSignal }): Promise<Document<T>>

• count(options?: {
    filter?: Filter;
    signal?: AbortSignal;
  }): Promise<number>

  How many documents match filter, or the whole collection.

• get(id: string, options?: { signal?: AbortSignal }): Promise<Document<T>>

• list(options?: ListOptions): Promise<Page<T>>

• pages(options?: ListOptions): AsyncIterable<Page<T>>

  Every page of a query in turn, following nextCursor from after (or the start). Not a snapshot: writes in between can shift later pages.

interface SiteCode

• mutate<R = Json>(
    name: string,
    args?: Json,
    options?: { signal?: AbortSignal },
  ): Promise<R>

  Runs an export of _naru/mutations/<module/path>.js in one transaction: what it wrote is kept only if it returns, and a throw, ctx.fail or a limit changes nothing.

• query<R = Json>(
    name: string,
    args?: Json,
    options?: { signal?: AbortSignal },
  ): Promise<R>

  Runs "<module/path>:<name>", an export of the site's _naru/queries/<module/path>.js, and resolves with what it returned. A query only reads (ctx.sql), so it counts against the caller's read budget.

class NaruError extends Error

• code: NaruErrorCode

• details?: Json

  The JSON a query or mutation passed as ctx.fail(code, message, details), such as { reason: "sold_out" }; or, when a member's request is refused because the site has not approved them, { membership: "pending" } or { membership: "banned" }; or, for a CONFLICT because another document already holds a value of one of the collection's unique fields, { unique: "<field>" }. Undefined for every other failure.

type Filter = Record<
  string,
  | string
  | number
  | boolean
  | null
  | {
      gt?: string | number;
      gte?: string | number;
      lt?: string | number;
      lte?: string | number;
    }
>

type Json =
  null | boolean | number | string | Json[] | { [key: string]: Json }

type NaruErrorCode =
  | "CONFLICT"
  | "QUOTA_EXCEEDED"
  | "AUTH_REQUIRED"
  | "ACCESS_DENIED"
  | "NOT_FOUND"
  | "RATE_LIMITED"
  | "INVALID_REQUEST"
  | "UNAVAILABLE"

type Revision = string & { [revisionBrand]: true }

type Sort =
  | readonly [
      readonly [
        string | { metadata: "id" | "createdAt" | "updatedAt" },
        "asc" | "desc",
      ],
    ]
  | readonly [
      readonly [
        string | { metadata: "id" | "createdAt" | "updatedAt" },
        "asc" | "desc",
      ],
      readonly [
        string | { metadata: "id" | "createdAt" | "updatedAt" },
        "asc" | "desc",
      ],
    ]

type WriteCondition = { revision: Revision } | { absent: true }