@naru-pub/dev 0.0.0-stage → 1.1.0

package/dist/chunk-K7ZVYKB2.mjs

@@ -0,0 +1,11 @@
+import {
+  packagedResources,
+  start
+} from "./chunk-CQFKRWOD.mjs";
+
+// src/index.ts
+var startNaru = (options) => start(options, packagedResources());
+
+export {
+  startNaru
+};

package/dist/cli.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import {
+  packagedInfo,
+  packagedResources,
+  start
+} from "./chunk-CQFKRWOD.mjs";
+
+// src/cli.ts
+import { readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+var HELP = `Usage: naru-dev [site folder] [options]
+
+Serves a Naru site locally: its pages, the Data SDK, _naru/ (migrations,
+queries, mutations, routes) on the real edge Worker, one-click owner and
+member sign-in, and uploads.
+
+Options:
+  --site <name>   the site's Naru name (<name>.naru.pub); default localsite
+  --port <port>   default 4000; 0 picks a free one
+  --state <dir>   where data is kept; default <site folder>/.naru-dev
+  --quiet         print only the address
+  --version       print the version and exit
+  --help          print this and exit
+`;
+async function main(argv, resources, info) {
+  const args = [...argv];
+  const flag = (name) => {
+    const index = args.indexOf(name);
+    return index >= 0 ? (args.splice(index, 1), true) : false;
+  };
+  const option = (name) => {
+    const index = args.indexOf(name);
+    if (index < 0) return void 0;
+    const value = args[index + 1];
+    if (value === void 0 || value.startsWith("--"))
+      throw new UsageError(`${name} needs a value.`);
+    return args.splice(index, 2)[1];
+  };
+  const sdk = readdirSync(resources.sdkDir).filter((name) => /^\d+\.\d+\.\d+$/.test(name)).sort();
+  const banner = `@naru-pub/dev ${info.version} (naru-pub ${info.commit}), SDK ${sdk.join(", ")}`;
+  try {
+    if (flag("--help") || flag("-h")) {
+      console.log(HELP);
+      return 0;
+    }
+    if (flag("--version") || flag("-v")) {
+      console.log(banner);
+      return 0;
+    }
+    const quiet = flag("--quiet");
+    const port = Number(option("--port") ?? 4e3);
+    if (!Number.isInteger(port) || port < 0 || port > 65535)
+      throw new UsageError("--port takes a port number.");
+    const name = option("--site");
+    if (name !== void 0 && !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name))
+      throw new UsageError(
+        "--site takes a Naru login name: lowercase letters, digits, hyphens."
+      );
+    const stateOption = option("--state");
+    const unknown = args.find((arg) => arg.startsWith("-"));
+    if (unknown) throw new UsageError(`Unknown option ${unknown}.`);
+    if (args.length > 1) throw new UsageError("Give one site folder.");
+    const folder = resolve(args[0] ?? ".");
+    if (!quiet) console.log(banner);
+    const naru = await start(
+      {
+        site: folder,
+        name,
+        port,
+        state: stateOption ? resolve(stateOption) : join(folder, ".naru-dev"),
+        quiet
+      },
+      resources
+    );
+    if (quiet) console.log(naru.origin);
+    await new Promise((done) => {
+      const stop = () => {
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+        void naru.stop().then(done);
+      };
+      process.on("SIGINT", stop);
+      process.on("SIGTERM", stop);
+    });
+    return 0;
+  } catch (error) {
+    if (error instanceof UsageError) {
+      console.error(`naru-dev: ${error.message}
+
+${HELP}`);
+      return 2;
+    }
+    console.error(`naru-dev: ${error.message}`);
+    return 1;
+  }
+}
+var UsageError = class extends Error {
+};
+
+// src/bin.ts
+process.exit(
+  await main(process.argv.slice(2), packagedResources(), packagedInfo())
+);

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+// @naru-pub/dev's public API: shipped as the package's types, and what
+// src/naru.ts implements (it imports these), so the two cannot disagree.
+
+export interface StartOptions {
+  /** The site's folder: its pages, and `_naru/` if it has one. */
+  site: string;
+  /**
+   * The site's Naru name, as in `<name>.naru.pub`: lowercase letters, digits
+   * and hyphens. Default `localsite`.
+   */
+  name?: string;
+  /** The port to serve on; 0 (the default) picks a free one. */
+  port?: number;
+  /**
+   * Where data, uploads and sign-ins are kept. Default: a new temporary
+   * folder, removed by `stop()`. The CLI keeps them in `<site>/.naru-dev/`.
+   */
+  state?: string;
+  /** Print nothing; `log` still has everything. */
+  quiet?: boolean;
+}
+
+/** Who signs in: the site's owner, or a test member by name. */
+export type Who = "owner" | (string & {});
+
+export interface SignInOptions {
+  /** A member's status, kept for later sign-ins too. Default `approved`. */
+  status?: "approved" | "pending" | "banned";
+  /**
+   * The owner's: collections to make private if missing, as Naru's sign-in
+   * page does for the collections a page asks for.
+   */
+  collections?: string[];
+}
+
+/** A sign-in, as the SDK keeps it, and a header for your own requests. */
+export interface Credentials {
+  accessToken: string;
+  /** Milliseconds since the epoch. */
+  expiresAt: number;
+  /** A member's id; absent for the owner. */
+  memberId?: string;
+  /** `{ authorization: "Bearer <accessToken>" }`, for fetch. */
+  headers: { authorization: string };
+}
+
+/**
+ * What `signIn` needs of a Playwright `Page` or `BrowserContext` (or any
+ * browser driver with the same methods).
+ */
+export interface BrowserTarget {
+  addInitScript(script: string): Promise<unknown>;
+  evaluate?(expression: string): Promise<unknown>;
+  url?(): string;
+}
+
+export interface Naru {
+  /** Where the site is served, such as `http://localhost:4000`. */
+  readonly origin: string;
+  /** The site's Naru name. */
+  readonly name: string;
+  /** The folder data is kept in. */
+  readonly state: string;
+  /** Everything printed so far, printed or not (`quiet`). */
+  readonly log: string;
+  /** `origin` + `path`. */
+  url(path?: string): string;
+  /**
+   * Signs `who` in. Given a page or browser context, its pages on this
+   * origin find the session where the SDK keeps it, from their next
+   * navigation (and at once, for a page already here). Returns the
+   * credentials either way, usable with fetch through `headers`.
+   */
+  signIn(
+    target: BrowserTarget | null | undefined,
+    who: Who,
+    options?: SignInOptions,
+  ): Promise<Credentials>;
+  /**
+   * Empties the site: its collections, tables and uploads. `_naru/` is
+   * published again, its migrations applied to the empty database; members
+   * and sign-ins are kept.
+   */
+  reset(): Promise<void>;
+  /** Stops the servers; removes `state` if `startNaru` made it. */
+  stop(): Promise<void>;
+}
+
+/** Serves `options.site` on a local Naru; resolves once it answers. */
+export function startNaru(options: StartOptions): Promise<Naru>;

package/dist/index.mjs

@@ -0,0 +1,7 @@
+import {
+  startNaru
+} from "./chunk-K7ZVYKB2.mjs";
+import "./chunk-CQFKRWOD.mjs";
+export {
+  startNaru
+};

package/dist/sdk/1.0.0/naru.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Naru Data SDK 1.0.0: browser SDK for data owned by one Naru site.
+ * @packageDocumentation
+ */
+
+export type Json =
+  | null
+  | boolean
+  | number
+  | string
+  | Json[]
+  | { [key: string]: Json };
+
+/** @internal */
+declare const revisionBrand: unique symbol;
+/** An opaque concurrency token. Store and return it unchanged. */
+export type Revision = string & { readonly [revisionBrand]: true };
+
+/** A read or successful write: user data stays separate from server metadata. */
+export interface Document<T = Json> {
+  id: string;
+  data: T;
+  createdAt: string;
+  updatedAt: string;
+  revision: Revision;
+}
+
+export interface Page<T = Json> {
+  documents: Document<T>[];
+  nextCursor: string | null;
+  totalCount?: number;
+}
+
+/**
+ * Why an operation failed. The list is closed for v1: a code a later server
+ * adds reaches this version as the nearest code here.
+ */
+export type NaruErrorCode =
+  | "CONFLICT"
+  | "QUOTA_EXCEEDED"
+  | "AUTH_REQUIRED"
+  | "ACCESS_DENIED"
+  | "NOT_FOUND"
+  | "RATE_LIMITED"
+  | "INVALID_REQUEST"
+  | "UNAVAILABLE";
+
+/** A Naru operation that could not be completed. Check it with `instanceof`. */
+export declare class NaruError extends Error {
+  private constructor();
+  readonly code: NaruErrorCode;
+}
+
+/** Top-level user fields, combined with AND. */
+export type Filter = Record<
+  string,
+  | string
+  | number
+  | boolean
+  | null
+  | {
+      gt?: string | number;
+      gte?: string | number;
+      lt?: string | number;
+      lte?: string | number;
+    }
+>;
+
+/** One or two keys: a user field by name, or document metadata. */
+export 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",
+      ],
+    ];
+
+export interface ListOptions {
+  filter?: Filter;
+  sort?: Sort;
+  /** Default 50; maximum 100. */
+  size?: number;
+  /** Opaque cursor returned by the preceding page. */
+  after?: string | null;
+  includeTotal?: boolean;
+  signal?: AbortSignal;
+}
+
+/** Write only at this revision, or only if the document does not exist yet. */
+export type WriteCondition = { revision: Revision } | { absent: true };
+
+export interface PublicCollection<T = Json> {
+  get(id: string, options?: { signal?: AbortSignal }): Promise<Document<T>>;
+  list(options?: ListOptions): Promise<Page<T>>;
+  /** How many documents match `filter`, or the whole collection. */
+  count(options?: { filter?: Filter; signal?: AbortSignal }): Promise<number>;
+  /**
+   * Every page of a query in turn, following `nextCursor` from `after` (or
+   * the start). Not a snapshot: writes in between can shift later pages.
+   */
+  pages(options?: ListOptions): AsyncIterable<Page<T>>;
+  add(data: T, options?: { signal?: AbortSignal }): Promise<Document<T>>;
+}
+
+export interface AdminCollection<T = Json> extends PublicCollection<T> {
+  /** Replaces the whole document or creates it. */
+  set(
+    id: string,
+    data: T,
+    options?: { condition?: WriteCondition; signal?: AbortSignal },
+  ): Promise<Document<T>>;
+  /** Deleting a missing document succeeds unless a condition was supplied. */
+  delete(
+    id: string,
+    options?: { condition?: { revision: Revision }; signal?: AbortSignal },
+  ): Promise<void>;
+}
+
+export interface Admin {
+  collection<T = Json>(name: string): AdminCollection<T>;
+  /**
+   * 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`.
+   */
+  batch(
+    writes: readonly (
+      | {
+          collection: string;
+          set: { id: string; data: unknown; condition?: WriteCondition };
+        }
+      | {
+          collection: string;
+          delete: { id: string; condition?: { revision: Revision } };
+        }
+    )[],
+    options?: { signal?: AbortSignal },
+  ): Promise<
+    ({
+      id: string;
+      revision: Revision;
+      createdAt: string;
+      updatedAt: string;
+    } | null)[]
+  >;
+  media: {
+    /**
+     * Stores a file publicly. Large photos may be shrunk first. A HEIC photo
+     * this browser cannot convert throws a `TypeError` before anything is sent.
+     */
+    upload(
+      file: File | Blob,
+      options?: {
+        signal?: AbortSignal;
+        /**
+         * Called as the upload moves along: `preparing` while a photo is
+         * shrunk and the upload authorized, `uploading` with the bytes sent
+         * so far of the `total` actually sent (after shrinking), then
+         * `finishing` while storage confirms and Naru records the file.
+         * `loaded` can reach `total` before storage has answered.
+         */
+        onProgress?: (
+          progress:
+            | { phase: "preparing" }
+            | { phase: "uploading"; loaded: number; total: number }
+            | { phase: "finishing" },
+        ) => void;
+      },
+    ): Promise<{
+      url: string;
+      name: string;
+      contentType: string;
+      size: number;
+    }>;
+  };
+  /** This handle stops working at once, even if the revoke request fails. */
+  signOut(): Promise<void>;
+}
+
+export interface NaruClient {
+  /** Visitor access, even when signed in. */
+  collection<T = Json>(name: string): PublicCollection<T>;
+  auth: {
+    /**
+     * The admin client for this page, or null. A sign-in that was denied,
+     * went stale or could not be exchanged also resolves null.
+     */
+    session(): Promise<Admin | null>;
+    /** Redirects to Naru for approval. */
+    signIn(options: { collections: readonly string[] }): Promise<void>;
+  };
+}
+
+/** Creates a client bound to one site. */
+export declare function createNaru(options?: { site?: string }): NaruClient;
+
+export {};