@thadeu/ndb 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,597 @@
+// src/errors.ts
+var NdbError = class extends Error {
+  code;
+  status;
+  constructor(code, message, status = 0) {
+    super(message ? `ndb: ${code}: ${message}` : `ndb: ${code}`);
+    this.name = new.target.name;
+    this.code = code;
+    this.status = status;
+  }
+};
+var UnauthorizedError = class extends NdbError {
+};
+var NotFoundError = class extends NdbError {
+};
+var VersionConflictError = class extends NdbError {
+};
+var DuplicateIdError = class extends NdbError {
+};
+var UniqueViolationError = class extends NdbError {
+};
+var InvalidQueryError = class extends NdbError {
+};
+var CursorError = class extends NdbError {
+};
+var WatchLaggedError = class extends NdbError {
+};
+var HistoryTruncatedError = class extends NdbError {
+};
+var TtlError = class extends NdbError {
+};
+var subclasses = {
+  unauthorized: UnauthorizedError,
+  not_found: NotFoundError,
+  unknown_collection: NotFoundError,
+  version_conflict: VersionConflictError,
+  duplicate_id: DuplicateIdError,
+  unique_violation: UniqueViolationError,
+  invalid_query: InvalidQueryError,
+  invalid_pipeline: InvalidQueryError,
+  cursor_invalid: CursorError,
+  cursor_mismatch: CursorError,
+  cursor_expired: CursorError,
+  watch_lagged: WatchLaggedError,
+  history_truncated: HistoryTruncatedError,
+  ttl_not_enabled: TtlError,
+  ttl_derived: TtlError
+};
+function makeError(code, message, status = 0) {
+  const Cls = subclasses[code] ?? NdbError;
+  return new Cls(code, message, status);
+}
+
+// src/where.ts
+var supportedFlags = /* @__PURE__ */ new Set(["i", "m", "s"]);
+function isPlain(v) {
+  if (typeof v !== "object" || v === null) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+function regexParts(re) {
+  const bad = [...re.flags].filter((f) => !supportedFlags.has(f));
+  if (bad.length > 0) {
+    throw new InvalidQueryError(
+      "invalid_query",
+      `RegExp flag "${bad.join("")}" is not supported by $regex (use i, m or s): ${String(re)}`
+    );
+  }
+  return re.flags === "" ? { $regex: re.source } : { $regex: re.source, $options: re.flags };
+}
+function operators(o) {
+  const out = {};
+  for (const [key, value] of Object.entries(o)) {
+    if (key === "$regex" && value instanceof RegExp) {
+      const parts = regexParts(value);
+      if (parts.$options !== void 0 && typeof o.$options === "string" && o.$options !== "") {
+        throw new InvalidQueryError("invalid_query", "use the RegExp flags or $options, not both");
+      }
+      out.$regex = parts.$regex;
+      if (parts.$options !== void 0) {
+        out.$options = parts.$options;
+      }
+      continue;
+    }
+    out[key] = toWhere(value);
+  }
+  return out;
+}
+function toWhere(v) {
+  if (v instanceof RegExp) {
+    return regexParts(v);
+  }
+  if (Array.isArray(v)) {
+    return v.map(toWhere);
+  }
+  if (isPlain(v)) {
+    return operators(v);
+  }
+  return v;
+}
+
+// src/query.ts
+var Query = class _Query {
+  constructor(model, state = { clauses: [] }) {
+    this.model = model;
+    this.state = state;
+  }
+  model;
+  state;
+  nextCursor = "";
+  where(w) {
+    return this.with({ clauses: [...this.state.clauses, toWhere(w)] });
+  }
+  not(w) {
+    return this.with({ clauses: [...this.state.clauses, { $not: toWhere(w) }] });
+  }
+  or(...ws) {
+    return this.with({ clauses: [...this.state.clauses, { $or: ws.map(toWhere) }] });
+  }
+  sort(spec) {
+    return this.with({ sort: { ...this.state.sort, ...spec } });
+  }
+  limit(n) {
+    return this.with({ limit: n });
+  }
+  skip(n) {
+    return this.with({ skip: n });
+  }
+  page(n, size) {
+    return this.with({ skip: (n - 1) * size, limit: size });
+  }
+  after(token) {
+    return this.with({ after: token });
+  }
+  fields(...names) {
+    return this.with({ fields: names });
+  }
+  then(onfulfilled, onrejected) {
+    return this.all().then(onfulfilled, onrejected);
+  }
+  async all() {
+    const out = [];
+    for await (const row of this.rows(this.body())) {
+      out.push(row);
+    }
+    return out;
+  }
+  async first() {
+    for await (const row of this.rows({ ...this.body(), limit: 1 })) {
+      return row;
+    }
+    return null;
+  }
+  async count() {
+    await this.model.ready();
+    const body = { where: this.whereDoc(), count: true, limit: 1 };
+    const res = await this.model.db.transport.stream("POST", this.model.path("find"), body);
+    await res.body.dump();
+    return Number(res.header("x-ndb-total") ?? 0);
+  }
+  async *iterate() {
+    let body = this.body();
+    for (; ; ) {
+      yield* this.rows(body);
+      if (this.nextCursor === "") {
+        return;
+      }
+      body = { ...body, after: this.nextCursor, skip: void 0 };
+    }
+  }
+  async *rows(body) {
+    await this.model.ready();
+    const res = await this.model.db.transport.stream("POST", this.model.path("find"), body);
+    this.nextCursor = res.header("x-ndb-next") ?? "";
+    for await (const raw of res.rows()) {
+      yield this.model.decode(raw);
+    }
+  }
+  body() {
+    const { fields, sort, limit, skip, after } = this.state;
+    return { where: this.whereDoc(), fields, sort, limit, skip, after, versions: true };
+  }
+  whereDoc() {
+    const merged = {};
+    for (const clause of this.state.clauses) {
+      for (const key of Object.keys(clause)) {
+        if (key in merged) {
+          return { $and: this.state.clauses };
+        }
+        merged[key] = clause[key];
+      }
+    }
+    return merged;
+  }
+  with(patch) {
+    return new _Query(this.model, { ...this.state, ...patch });
+  }
+};
+
+// src/watch.ts
+async function* watchEvents(lines2, consumer) {
+  for await (const raw of lines2) {
+    const line = raw;
+    if (line.heartbeat) {
+      continue;
+    }
+    if (line.error) {
+      throw makeError(line.error.code, line.error.message);
+    }
+    yield { consumer, pos: line.pos, op: line.op, id: line.id, v: line.v, doc: line.doc };
+  }
+}
+
+// src/model.ts
+var Model = class {
+  constructor(db, name, schema) {
+    this.db = db;
+    this.name = name;
+    this.schema = schema;
+  }
+  db;
+  name;
+  schema;
+  ensured;
+  get idField() {
+    return this.schema.id ?? "_id";
+  }
+  path(op) {
+    const base = `/v1/c/${encodeURIComponent(this.name)}`;
+    return op ? `${base}/${op}` : base;
+  }
+  ready() {
+    this.ensured ??= this.db.transport.request("PUT", this.path(), this.catalog()).catch((err) => {
+      this.ensured = void 0;
+      throw err;
+    });
+    return this.ensured;
+  }
+  async insert(docs, opts = {}) {
+    await this.ready();
+    const list = Array.isArray(docs) ? docs : [docs];
+    const out = await this.db.transport.request("POST", this.path("insert"), {
+      insert: list,
+      expire_in: opts.expireIn
+    });
+    return out.results;
+  }
+  create(docs, opts = {}) {
+    return this.insert(docs, opts);
+  }
+  async update(id, set, opts = {}) {
+    await this.ready();
+    const update = { id, set, unset: opts.unset, if_version: opts.ifVersion, expire_in: opts.expireIn };
+    return this.db.transport.request("POST", this.path("update"), { update });
+  }
+  async delete(id, opts = {}) {
+    await this.ready();
+    await this.db.transport.request("POST", this.path("delete"), { delete: { id, if_version: opts.ifVersion } });
+  }
+  // Makes a document expire, like EXPIRE in Redis: seconds or "30m". It throws
+  // NotFoundError for a missing or expired document, and TtlError when the
+  // schema has no expires field.
+  expire(id, duration, opts = {}) {
+    return this.setExpiry({ id, in: duration, if_version: opts.ifVersion });
+  }
+  expireAt(id, at, opts = {}) {
+    return this.setExpiry({ id, at: at.toISOString(), if_version: opts.ifVersion });
+  }
+  // Removes the expiry of a document (PERSIST in Redis).
+  async persist(id) {
+    await this.ready();
+    return this.db.transport.request("POST", this.path("persist"), { id });
+  }
+  // The seconds left (rounded up), -1 when the document never expires, null
+  // when it is missing or expired.
+  async ttl(id) {
+    await this.ready();
+    try {
+      const out = await this.db.transport.request("GET", `${this.path("ttl")}/${encodeURIComponent(id)}`);
+      return out.ttl;
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        return null;
+      }
+      throw err;
+    }
+  }
+  async setExpiry(body) {
+    await this.ready();
+    const out = await this.db.transport.request("POST", this.path("expire"), body);
+    return { id: out.id, v: out.v, expiresAt: new Date(out.expires_at) };
+  }
+  find(id) {
+    return this.query().where({ [this.idField]: id }).first();
+  }
+  query() {
+    return new Query(this);
+  }
+  where(w) {
+    return this.query().where(w);
+  }
+  not(w) {
+    return this.query().not(w);
+  }
+  or(...ws) {
+    return this.query().or(...ws);
+  }
+  sort(spec) {
+    return this.query().sort(spec);
+  }
+  limit(n) {
+    return this.query().limit(n);
+  }
+  skip(n) {
+    return this.query().skip(n);
+  }
+  page(n, size) {
+    return this.query().page(n, size);
+  }
+  after(token) {
+    return this.query().after(token);
+  }
+  fields(...names) {
+    return this.query().fields(...names);
+  }
+  all() {
+    return this.query().all();
+  }
+  count() {
+    return this.query().count();
+  }
+  first() {
+    return this.query().first();
+  }
+  iterate() {
+    return this.query().iterate();
+  }
+  async aggregate(pipeline, opts = {}) {
+    await this.ready();
+    const res = await this.db.transport.stream("POST", this.path("aggregate"), { pipeline, ...opts });
+    const rows = [];
+    for await (const row of res.rows()) {
+      rows.push(row);
+    }
+    return { rows, next: res.header("x-ndb-next") ?? "", total: Number(res.header("x-ndb-total") ?? 0) };
+  }
+  async *watch(consumer, opts = {}) {
+    await this.ready();
+    const body = { consumer, from: opts.from, limit: opts.limit, where: opts.where === void 0 ? void 0 : toWhere(opts.where) };
+    const res = await this.db.transport.stream("POST", this.path("watch"), body, opts.signal);
+    for await (const ev of watchEvents(res.rows(), consumer)) {
+      yield { ...ev, doc: ev.doc && this.decode(ev.doc) };
+    }
+  }
+  async ack(event) {
+    await this.db.transport.request("POST", this.path("ack"), { consumer: event.consumer, pos: event.pos });
+  }
+  decode(raw) {
+    const out = { ...raw };
+    for (const [name, def] of Object.entries(this.schema.fields)) {
+      const v = out[name];
+      if (def.type === "date" && typeof v === "string") {
+        out[name] = new Date(v);
+      }
+    }
+    return out;
+  }
+  catalog() {
+    const entries = Object.entries(this.schema.fields);
+    return {
+      id: this.schema.id,
+      time: this.schema.time,
+      expires_field: this.schema.expires,
+      indexes: entries.filter(([, d]) => d.index).map(([n]) => n),
+      unique: entries.filter(([, d]) => d.unique).map(([n]) => n)
+    };
+  }
+};
+
+// src/transport.ts
+import { Pool } from "undici";
+
+// src/ndjson.ts
+async function* lines(body) {
+  let rest = "";
+  body.setEncoding("utf8");
+  for await (const chunk of body) {
+    rest += chunk;
+    let at = rest.indexOf("\n");
+    while (at >= 0) {
+      const line = rest.slice(0, at);
+      rest = rest.slice(at + 1);
+      if (line.trim() !== "") {
+        yield line;
+      }
+      at = rest.indexOf("\n");
+    }
+  }
+  if (rest.trim() !== "") {
+    yield rest;
+  }
+}
+async function* jsonRows(body) {
+  for await (const line of lines(body)) {
+    yield JSON.parse(line);
+  }
+}
+
+// src/transport.ts
+var staleSocket = /* @__PURE__ */ new Set(["UND_ERR_SOCKET", "ECONNRESET", "EPIPE"]);
+var notConnected = /* @__PURE__ */ new Set(["ECONNREFUSED", "ENOENT"]);
+var retryBaseMs = 50;
+var retryCapMs = 1e3;
+var defaultReadyTimeoutMs = 1e4;
+var readOps = /\/(find|count|aggregate|get|stats)$/;
+var Transport = class {
+  client;
+  token;
+  readyTimeout;
+  // addr: unix:///path or tcp://host:port. Default: env NDB_URL.
+  constructor(addr, opts = {}) {
+    const target = addr || process.env.NDB_URL || "";
+    const url = new URL(target);
+    this.token = opts.token || process.env.NDB_TOKEN || void 0;
+    this.readyTimeout = opts.readyTimeout ?? defaultReadyTimeoutMs;
+    if (url.protocol === "unix:" && url.pathname !== "") {
+      this.client = new Pool("http://ndb", { socketPath: decodeURIComponent(url.pathname), connections: 16 });
+    } else if (url.protocol === "tcp:" && url.host !== "") {
+      this.client = new Pool(`http://${url.host}`, { connections: 16 });
+    } else {
+      throw new TypeError(`ndb: address "${target}" must be unix:///path or tcp://host:port`);
+    }
+  }
+  async stream(method, path, body, signal) {
+    const res = await this.withReadyRetry(method, path, signal, async () => {
+      const r = await this.send(method, path, body, signal);
+      if (r.statusCode >= 300) {
+        throw await apiError(r);
+      }
+      return r;
+    });
+    return {
+      status: res.statusCode,
+      headers: res.headers,
+      body: res.body,
+      rows: () => jsonRows(res.body),
+      header: (name) => headerOf(res.headers, name)
+    };
+  }
+  async request(method, path, body) {
+    const res = await this.stream(method, path, body);
+    const text = await res.body.setEncoding("utf8").toArray();
+    return text.length > 0 ? JSON.parse(text.join("")) : void 0;
+  }
+  close() {
+    return this.client.close();
+  }
+  // Runs fn again while the daemon is not ready, with exponential backoff and
+  // jitter. It repeats only when the request certainly was not processed
+  // (not_ready, a failed connect), or for a read whose connection dropped.
+  // When the deadline passes, the last error is thrown as it was.
+  async withReadyRetry(method, path, signal, fn) {
+    const deadline = Date.now() + this.readyTimeout;
+    const idempotent = isIdempotent(method, path);
+    let delay = retryBaseMs;
+    for (; ; ) {
+      try {
+        return await fn();
+      } catch (err) {
+        const wait = delay / 2 + Math.random() * (delay / 2);
+        if (this.readyTimeout <= 0 || signal?.aborted || !retryable(err, idempotent) || Date.now() + wait > deadline) {
+          throw err;
+        }
+        await sleep(wait, signal);
+        delay = Math.min(delay * 2, retryCapMs);
+      }
+    }
+  }
+  headers() {
+    const headers = { "content-type": "application/json" };
+    if (this.token) {
+      headers.authorization = `Bearer ${this.token}`;
+    }
+    return headers;
+  }
+  async send(method, path, body, signal) {
+    const opts = {
+      method,
+      path,
+      signal,
+      headers: this.headers(),
+      body: body === void 0 ? void 0 : JSON.stringify(body)
+    };
+    try {
+      return await this.client.request(opts);
+    } catch (err) {
+      if (!isIdempotent(method, path) || !staleSocket.has(err.code ?? "") || signal?.aborted) {
+        throw err;
+      }
+      return await this.client.request(opts);
+    }
+  }
+};
+function isIdempotent(method, path) {
+  return method === "GET" || readOps.test(path.split("?")[0] ?? path);
+}
+function errorCodes(err) {
+  const e = err;
+  const nested = [...e.errors ?? [], ...e.cause ? [e.cause] : []];
+  return [e.code ?? "", ...nested.flatMap(errorCodes)];
+}
+function retryable(err, idempotent) {
+  if (err instanceof NdbError) {
+    return err.code === "not_ready";
+  }
+  const codes = errorCodes(err);
+  if (codes.some((c) => notConnected.has(c))) {
+    return true;
+  }
+  return idempotent && codes.some((c) => staleSocket.has(c));
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+function headerOf(headers, name) {
+  const v = headers[name.toLowerCase()];
+  return Array.isArray(v) ? v[0] : v;
+}
+async function apiError(res) {
+  const text = (await res.body.setEncoding("utf8").toArray()).join("");
+  try {
+    const { error, status } = JSON.parse(text);
+    if (res.statusCode === 503 && status === "recovering") {
+      return makeError("not_ready", "ndb is recovering", 503);
+    }
+    if (error?.code) {
+      return makeError(error.code, error.message ?? "", res.statusCode);
+    }
+  } catch {
+    return makeError("http_status", text.trim(), res.statusCode);
+  }
+  return makeError("http_status", text.trim(), res.statusCode);
+}
+
+// src/ndb.ts
+var Ndb = class {
+  transport;
+  constructor(addr, opts) {
+    this.transport = new Transport(addr, opts);
+  }
+  model(name, schema) {
+    return new Model(this, name, schema);
+  }
+  async health() {
+    await this.transport.request("GET", "/health");
+  }
+  request(method, path, body) {
+    return this.transport.request(method, path, body);
+  }
+  stream(...args) {
+    return this.transport.stream(...args);
+  }
+  close() {
+    return this.transport.close();
+  }
+};
+function connect(addr, opts) {
+  return new Ndb(addr, opts);
+}
+export {
+  CursorError,
+  DuplicateIdError,
+  HistoryTruncatedError,
+  InvalidQueryError,
+  Model,
+  Ndb,
+  NdbError,
+  NotFoundError,
+  Query,
+  TtlError,
+  UnauthorizedError,
+  UniqueViolationError,
+  VersionConflictError,
+  WatchLaggedError,
+  connect,
+  makeError
+};

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@thadeu/ndb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "TypeScript client for the ndb daemon",
+  "keywords": [
+    "ndb",
+    "ndjson",
+    "database",
+    "client"
+  ],
+  "homepage": "https://github.com/thadeu/ndb#readme",
+  "bugs": {
+    "url": "https://github.com/thadeu/ndb/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thadeu/ndb.git",
+    "directory": "sdk/ts"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "undici": "^8.12.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/node": "^26.6.6",
+    "eslint": "^10.14.0",
+    "tsup": "^9.0.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vitest": "^5.1.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}