@dotteamdev/sensdb 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# Sens — TypeScript client
+
+A zero-dependency `fetch` client for a `sens serve` HTTP/JSON endpoint. Works in
+Node 18+, Bun, Deno, and any runtime with a global `fetch`.
+
+> **Server-side only.** Keep the token on the server (Next.js route handlers /
+> server actions, NestJS providers). Never ship it to the browser. Always pass
+> user input via `params` — never string-concatenate SQL.
+
+## Setup
+
+Copy `sens.ts` into your project (an npm package with prebuilds is on the
+roadmap). Start a server:
+
+```bash
+sens serve app.db --port 8080 --token "$(openssl rand -hex 16)"
+```
+
+```ts
+import { createClient } from "./sens";
+
+const db = createClient(process.env.SENS_URL!, { token: process.env.SENS_TOKEN });
+
+// parameterized query — user input goes in params, never in the SQL string
+const { columns, rows } = await db.query(
+  "SELECT id, title FROM docs WHERE author = ?",
+  [author],
+);
+```
+
+## Next.js (App Router — server side)
+
+```ts
+// app/api/search/route.ts
+import { NextResponse } from "next/server";
+import { createClient } from "@/lib/sens";
+
+const db = createClient(process.env.SENS_URL!, { token: process.env.SENS_TOKEN });
+
+export async function POST(req: Request) {
+  const { embedding } = await req.json(); // number[] from your embedding model
+  // AI-native semantic search: nearest documents to the query vector
+  const { rows } = await db.query(
+    "SELECT title FROM docs ORDER BY embed <-> ? LIMIT 5",
+    [embedding],
+  );
+  return NextResponse.json({ results: rows.map((r) => r[0]) });
+}
+```
+
+## NestJS (a provider)
+
+```ts
+// sens.service.ts
+import { Injectable } from "@nestjs/common";
+import { createClient, SensClient } from "./sens";
+
+@Injectable()
+export class SensService {
+  private db: SensClient = createClient(process.env.SENS_URL!, {
+    token: process.env.SENS_TOKEN,
+  });
+
+  async docsByAuthor(author: string) {
+    const { rows } = await this.db.query(
+      "SELECT id, title FROM docs WHERE author = ? ORDER BY id",
+      [author],
+    );
+    return rows;
+  }
+
+  async semanticSearch(embedding: number[], k = 5) {
+    const { rows } = await this.db.query(
+      "SELECT title FROM docs ORDER BY embed <-> ? LIMIT ?",
+      [embedding, k],
+    );
+    return rows.map((r) => r[0]);
+  }
+}
+```
+
+## API
+
+- `createClient(baseUrl, { token?, fetch? })` → `SensClient`
+- `client.query(sql, params?)` → `Promise<{ columns, rows }>` — throws `SensError` on failure
+- `client.health()` → `Promise<{ status, version }>`
+
+Value mapping (JSON ↔ Sens): number ↔ INTEGER/REAL, string ↔ TEXT,
+boolean ↔ BOOLEAN, null ↔ NULL, `number[]` ↔ VECTOR.

package/dist/sens.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Sens TypeScript client — zero dependencies, uses only `fetch`.
+ *
+ * Talks to a `sens serve` HTTP/JSON endpoint. Server-side only: keep the token
+ * on the server (Next.js route handlers / server actions, NestJS providers) and
+ * never expose it to the browser. Always pass user input as `params` — never
+ * concatenate it into the SQL string.
+ */
+export type SensValue = number | string | boolean | null | number[];
+export interface SensResult {
+    /** Column names, in order. Empty for non-SELECT statements. */
+    columns: string[];
+    /** Result rows; each row is an array of values aligned with `columns`. */
+    rows: SensValue[][];
+}
+export declare class SensError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+export interface SensClient {
+    /** Run a (parameterized) SQL statement. `?` placeholders are filled from `params`. */
+    query(sql: string, params?: SensValue[]): Promise<SensResult>;
+    /** Server health + version. */
+    health(): Promise<{
+        status: string;
+        version: string;
+    }>;
+}
+export interface SensClientOptions {
+    /** Bearer token, if the server was started with --token. */
+    token?: string;
+    /** Optional custom fetch (e.g. for tests or a proxy). Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Create a Sens client bound to a `sens serve` base URL, e.g.
+ *   const db = createClient("http://127.0.0.1:8080", { token: process.env.SENS_TOKEN });
+ */
+export declare function createClient(baseUrl: string, opts?: SensClientOptions): SensClient;

package/dist/sens.js

@@ -0,0 +1,56 @@
+/**
+ * Sens TypeScript client — zero dependencies, uses only `fetch`.
+ *
+ * Talks to a `sens serve` HTTP/JSON endpoint. Server-side only: keep the token
+ * on the server (Next.js route handlers / server actions, NestJS providers) and
+ * never expose it to the browser. Always pass user input as `params` — never
+ * concatenate it into the SQL string.
+ */
+export class SensError extends Error {
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "SensError";
+    }
+}
+/**
+ * Create a Sens client bound to a `sens serve` base URL, e.g.
+ *   const db = createClient("http://127.0.0.1:8080", { token: process.env.SENS_TOKEN });
+ */
+export function createClient(baseUrl, opts = {}) {
+    const url = baseUrl.replace(/\/+$/, "");
+    const doFetch = opts.fetch ?? fetch;
+    const headers = { "content-type": "application/json" };
+    if (opts.token) {
+        headers["authorization"] = `Bearer ${opts.token}`;
+    }
+    return {
+        async query(sql, params = []) {
+            const res = await doFetch(`${url}/query`, {
+                method: "POST",
+                headers,
+                body: JSON.stringify({ sql, params }),
+            });
+            const text = await res.text();
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new SensError(`invalid response from server: ${text.slice(0, 200)}`, res.status);
+            }
+            const obj = data;
+            if (!res.ok || obj.error) {
+                throw new SensError(obj.error ?? `HTTP ${res.status}`, res.status);
+            }
+            return { columns: obj.columns ?? [], rows: obj.rows ?? [] };
+        },
+        async health() {
+            const res = await doFetch(`${url}/health`);
+            if (!res.ok) {
+                throw new SensError(`HTTP ${res.status}`, res.status);
+            }
+            return (await res.json());
+        },
+    };
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@dotteamdev/sensdb",
+  "version": "0.1.0",
+  "description": "Zero-dependency TypeScript client for a Sens (sens serve) HTTP/JSON endpoint — relational + AI-native (vector/semantic search) database.",
+  "type": "module",
+  "main": "./dist/sens.js",
+  "module": "./dist/sens.js",
+  "types": "./dist/sens.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/sens.d.ts",
+      "import": "./dist/sens.js"
+    }
+  },
+  "files": [
+    "dist",
+    "sens.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "sens",
+    "database",
+    "sql",
+    "vector",
+    "semantic-search",
+    "embeddings",
+    "ai",
+    "client"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "sideEffects": false
+}

package/sens.ts

@@ -0,0 +1,81 @@
+/**
+ * Sens TypeScript client — zero dependencies, uses only `fetch`.
+ *
+ * Talks to a `sens serve` HTTP/JSON endpoint. Server-side only: keep the token
+ * on the server (Next.js route handlers / server actions, NestJS providers) and
+ * never expose it to the browser. Always pass user input as `params` — never
+ * concatenate it into the SQL string.
+ */
+
+export type SensValue = number | string | boolean | null | number[];
+
+export interface SensResult {
+  /** Column names, in order. Empty for non-SELECT statements. */
+  columns: string[];
+  /** Result rows; each row is an array of values aligned with `columns`. */
+  rows: SensValue[][];
+}
+
+export class SensError extends Error {
+  constructor(message: string, readonly status?: number) {
+    super(message);
+    this.name = "SensError";
+  }
+}
+
+export interface SensClient {
+  /** Run a (parameterized) SQL statement. `?` placeholders are filled from `params`. */
+  query(sql: string, params?: SensValue[]): Promise<SensResult>;
+  /** Server health + version. */
+  health(): Promise<{ status: string; version: string }>;
+}
+
+export interface SensClientOptions {
+  /** Bearer token, if the server was started with --token. */
+  token?: string;
+  /** Optional custom fetch (e.g. for tests or a proxy). Defaults to global fetch. */
+  fetch?: typeof fetch;
+}
+
+/**
+ * Create a Sens client bound to a `sens serve` base URL, e.g.
+ *   const db = createClient("http://127.0.0.1:8080", { token: process.env.SENS_TOKEN });
+ */
+export function createClient(baseUrl: string, opts: SensClientOptions = {}): SensClient {
+  const url = baseUrl.replace(/\/+$/, "");
+  const doFetch = opts.fetch ?? fetch;
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (opts.token) {
+    headers["authorization"] = `Bearer ${opts.token}`;
+  }
+
+  return {
+    async query(sql: string, params: SensValue[] = []): Promise<SensResult> {
+      const res = await doFetch(`${url}/query`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ sql, params }),
+      });
+      const text = await res.text();
+      let data: unknown;
+      try {
+        data = JSON.parse(text);
+      } catch {
+        throw new SensError(`invalid response from server: ${text.slice(0, 200)}`, res.status);
+      }
+      const obj = data as { error?: string; columns?: string[]; rows?: SensValue[][] };
+      if (!res.ok || obj.error) {
+        throw new SensError(obj.error ?? `HTTP ${res.status}`, res.status);
+      }
+      return { columns: obj.columns ?? [], rows: obj.rows ?? [] };
+    },
+
+    async health(): Promise<{ status: string; version: string }> {
+      const res = await doFetch(`${url}/health`);
+      if (!res.ok) {
+        throw new SensError(`HTTP ${res.status}`, res.status);
+      }
+      return (await res.json()) as { status: string; version: string };
+    },
+  };
+}