locusdb-client 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# locusdb-client
+
+The Node.js client for [Locus](https://github.com/intenttext/locus). Any Redis
+driver works against Locus for standard commands — this package adds the two
+things a plain driver can't give you ergonomically:
+
+1. **Typed helpers** for the differentiator verbs (geo, sketches, CAS, secondary
+   index, cross-shard changefeed) so you get types and autocomplete instead of
+   stringly-typed `redis.call(...)`.
+2. **The reactive API** — a live **changefeed** and **geofence** delivered as
+   events. Locus streams these as a custom push protocol that `ioredis` doesn't
+   model, so the client owns a dedicated connection and parses the frames for you.
+
+It wraps `ioredis` (exposed as `.redis`) — it does not reimplement RESP.
+
+## Install
+
+```bash
+npm install locusdb-client ioredis
+```
+
+## Use
+
+```ts
+import { LocusClient } from "locusdb-client";
+
+const locus = new LocusClient({ host: "127.0.0.1", port: 6379 });
+
+// Standard Redis: the raw ioredis connection is right there.
+await locus.redis.set("hello", "world");
+
+// Differentiator verbs, typed:
+await locus.geoSet("driver:7", 13.36, 38.11, { status: "free" });
+const hits = await locus.geoSearch({
+  fromLonLat: [13.4, 38.1],
+  byRadius: [50, "km"],
+  withDist: true,
+  where: { status: "free" }, // attribute filter
+});
+// hits -> [{ key: "driver:7", dist: 3.67 }]
+
+await locus.bfAdd("seen", "msg-42");        // 1 new, 0 probably-duplicate
+await locus.cas("flag", "old", "new");      // atomic check-and-set
+await locus.idxCreate("by_status", "status");
+await locus.idxGet("by_status", "paid");    // -> ["order:1"]
+```
+
+### Live changefeed (push)
+
+```ts
+const feed = locus.changefeed("user:");      // optional key prefix
+feed.on("ready", ({ count, offset }) => console.log("snapshot done", count));
+feed.on("change", (c) => console.log(c.op, c.key, c.value)); // write | del | expire
+// ...later
+feed.close();
+```
+
+### Live geofencing
+
+```ts
+const fence = locus.geofence(13.4, 38.1, 5, "km");
+fence.on("enter", (m) => console.log("entered", m.key, m.value)); // "lon,lat"
+fence.on("move",  (m) => console.log("moved",   m.key, m.value));
+fence.on("leave", (m) => console.log("left",    m.key));
+```
+
+Both run on their own connection; the snapshot (`"snapshot"` events, then
+`"ready"`) precedes live updates, so there's no gap or duplicate.
+
+### Cross-shard changefeed (clustered)
+
+```ts
+let since = 0;
+for (;;) {
+  const batch = await locus.clusterCdcMerge(since, 100); // global HLC order
+  for (const c of batch) { handle(c); since = c.hlc; }
+  if (!batch.length) await new Promise((r) => setTimeout(r, 250));
+}
+```
+
+## Notes
+
+- Pull-style changefeed (`cdcRead`) and consumer groups work over the normal
+  connection and need server retention (`LOCUS_CDC_MAXLEN`). The push API above
+  does not.
+- For TLS, pass ioredis's `tls` option; the subscription connection honors it too.
+- See the [changefeed](../../docs/CHANGEFEED.md) and [geo](../../docs/GEO.md) docs
+  for semantics, and [COMMANDS.md](../../docs/COMMANDS.md) for the full surface.
+
+Run the example against a local server: `node examples/quickstart.cjs` (after
+`npm run build`).

package/dist/changefeed.d.ts

@@ -0,0 +1,62 @@
+import { EventEmitter } from "node:events";
+import net from "node:net";
+/** Connection details for a dedicated subscription socket. */
+export interface SubscribeOptions {
+    host: string;
+    port: number;
+    password?: string;
+    tls?: boolean;
+}
+/** One keyspace change delivered live. `value` is the new string for writes, null otherwise. */
+export interface Change {
+    offset: number;
+    op: "write" | "del" | "expire" | string;
+    key: string;
+    value: string | null;
+}
+/** A geofence membership event. */
+export interface GeoEvent {
+    key: string;
+    value: string | null;
+}
+/**
+ * A live changefeed subscription on its own connection (Locus pushes the
+ * snapshot then live frames; a plain Redis driver can't model this custom push
+ * command, so we own the socket and parse the frames ourselves).
+ *
+ * Events:
+ *  - `"snapshot"` ({@link GeoEvent})  one per key in the initial atomic snapshot
+ *  - `"ready"`    ({ count, offset }) snapshot complete; live changes follow
+ *  - `"change"`   ({@link Change})    a live keyspace change
+ *  - `"error"`    (Error)             socket error
+ *  - `"close"`    ()                  connection closed
+ */
+export declare class Changefeed extends EventEmitter {
+    private readonly opts;
+    private readonly command;
+    protected socket?: net.Socket;
+    private reader;
+    private closed;
+    constructor(opts: SubscribeOptions, command: string[]);
+    private connect;
+    private write;
+    private onConnect;
+    private dispatch;
+    /** Close the subscription connection and drop all listeners. Destroys the
+     *  socket so it releases the event loop (a graceful end() can hang waiting on
+     *  the server). */
+    close(): void;
+}
+/**
+ * A live geofence: subscribe to a circular region and get membership
+ * transitions. Tracks members so it can distinguish first entry from movement.
+ *
+ * Events (in addition to the base {@link Changefeed} events):
+ *  - `"enter"` ({@link GeoEvent}) a key entered the region
+ *  - `"move"`  ({@link GeoEvent}) a key already inside moved
+ *  - `"leave"` ({@link GeoEvent}) a key left the region
+ */
+export declare class Geofence extends Changefeed {
+    private readonly members;
+    constructor(opts: SubscribeOptions, lon: number, lat: number, radius: number, unit?: string);
+}

package/dist/changefeed.js

@@ -0,0 +1,128 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Geofence = exports.Changefeed = void 0;
+const node_events_1 = require("node:events");
+const node_net_1 = __importDefault(require("node:net"));
+const node_tls_1 = __importDefault(require("node:tls"));
+const resp_1 = require("./resp");
+/**
+ * A live changefeed subscription on its own connection (Locus pushes the
+ * snapshot then live frames; a plain Redis driver can't model this custom push
+ * command, so we own the socket and parse the frames ourselves).
+ *
+ * Events:
+ *  - `"snapshot"` ({@link GeoEvent})  one per key in the initial atomic snapshot
+ *  - `"ready"`    ({ count, offset }) snapshot complete; live changes follow
+ *  - `"change"`   ({@link Change})    a live keyspace change
+ *  - `"error"`    (Error)             socket error
+ *  - `"close"`    ()                  connection closed
+ */
+class Changefeed extends node_events_1.EventEmitter {
+    constructor(opts, command) {
+        super();
+        this.opts = opts;
+        this.command = command;
+        this.reader = new resp_1.RespReader();
+        this.closed = false;
+        this.connect();
+    }
+    connect() {
+        const { host, port } = this.opts;
+        const sock = this.opts.tls
+            ? node_tls_1.default.connect({ host, port, rejectUnauthorized: false })
+            : node_net_1.default.connect({ host, port });
+        this.socket = sock;
+        const ready = () => this.onConnect();
+        sock.once(this.opts.tls ? "secureConnect" : "connect", ready);
+        sock.on("data", (d) => {
+            for (const frame of this.reader.push(d))
+                this.dispatch(frame);
+        });
+        sock.on("error", (e) => this.emit("error", e));
+        sock.on("close", () => {
+            if (!this.closed)
+                this.emit("close");
+        });
+    }
+    write(args) {
+        let out = `*${args.length}\r\n`;
+        for (const a of args)
+            out += `$${Buffer.byteLength(a)}\r\n${a}\r\n`;
+        this.socket?.write(out);
+    }
+    onConnect() {
+        if (this.opts.password)
+            this.write(["AUTH", this.opts.password]);
+        this.write(this.command);
+    }
+    dispatch(frame) {
+        if (!Array.isArray(frame) || typeof frame[0] !== "string")
+            return; // +OK etc.
+        switch (frame[0]) {
+            case "cdc-snapshot":
+                this.emit("snapshot", {
+                    key: String(frame[1]),
+                    value: (frame[2] ?? null),
+                });
+                break;
+            case "cdc-snapshot-done":
+                this.emit("ready", { count: Number(frame[1]), offset: Number(frame[2]) });
+                break;
+            case "cdc-change":
+                this.emit("change", {
+                    offset: Number(frame[1]),
+                    op: String(frame[2]),
+                    key: String(frame[3]),
+                    value: (frame[4] ?? null),
+                });
+                break;
+        }
+    }
+    /** Close the subscription connection and drop all listeners. Destroys the
+     *  socket so it releases the event loop (a graceful end() can hang waiting on
+     *  the server). */
+    close() {
+        this.closed = true;
+        this.socket?.destroy();
+        this.removeAllListeners();
+    }
+}
+exports.Changefeed = Changefeed;
+/**
+ * A live geofence: subscribe to a circular region and get membership
+ * transitions. Tracks members so it can distinguish first entry from movement.
+ *
+ * Events (in addition to the base {@link Changefeed} events):
+ *  - `"enter"` ({@link GeoEvent}) a key entered the region
+ *  - `"move"`  ({@link GeoEvent}) a key already inside moved
+ *  - `"leave"` ({@link GeoEvent}) a key left the region
+ */
+class Geofence extends Changefeed {
+    constructor(opts, lon, lat, radius, unit = "km") {
+        super(opts, [
+            "CDCSUBSCRIBE",
+            "REGION",
+            String(lon),
+            String(lat),
+            String(radius),
+            unit,
+        ]);
+        this.members = new Set();
+        this.on("snapshot", (s) => this.members.add(s.key));
+        this.on("change", (c) => {
+            if (c.op === "del") {
+                this.members.delete(c.key);
+                this.emit("leave", { key: c.key, value: null });
+            }
+            else {
+                const inside = this.members.has(c.key);
+                this.members.add(c.key);
+                this.emit(inside ? "move" : "enter", { key: c.key, value: c.value });
+            }
+        });
+    }
+}
+exports.Geofence = Geofence;

package/dist/client.d.ts

@@ -0,0 +1,81 @@
+import Redis, { RedisOptions } from "ioredis";
+import { Change, Changefeed, Geofence } from "./changefeed";
+export type LocusOptions = RedisOptions;
+/** A `GEOSEARCH` query. Provide exactly one origin and exactly one shape. */
+export interface GeoSearchQuery {
+    fromLonLat?: [number, number];
+    fromMember?: string;
+    byRadius?: [number, GeoUnit];
+    byBox?: [number, number, GeoUnit];
+    order?: "ASC" | "DESC";
+    count?: number;
+    withCoord?: boolean;
+    withDist?: boolean;
+    /** Inline attribute equality filters (AND), e.g. `{ status: "free" }`. */
+    where?: Record<string, string>;
+}
+export type GeoUnit = "m" | "km" | "mi" | "ft";
+/** One `GEOSEARCH` hit; `dist`/`coord` are present only if requested. */
+export interface GeoHit {
+    key: string;
+    dist?: number;
+    coord?: [number, number];
+}
+/**
+ * A Locus client. Wraps `ioredis` for every request/reply command (standard
+ * Redis ops via `.redis`, the differentiator verbs via the typed helpers here)
+ * and adds the reactive APIs — {@link changefeed} and {@link geofence} — that a
+ * plain Redis driver can't surface.
+ */
+export declare class LocusClient {
+    /** The underlying ioredis connection — use it for any standard Redis command. */
+    readonly redis: Redis;
+    private readonly sub;
+    constructor(options?: LocusOptions);
+    /** Store a geo point, with optional inline attributes for `where` filtering. */
+    geoSet(key: string, lon: number, lat: number, attrs?: Record<string, string>): Promise<unknown>;
+    /** `[lon, lat]` for a key, or null if absent. */
+    geoPos(key: string): Promise<[number, number] | null>;
+    /** Distance between two geo keys in `unit` (default meters). */
+    geoDist(a: string, b: string, unit?: GeoUnit): Promise<number | null>;
+    /** Spatial search; returns parsed hits (cluster-aware — the server merges shards). */
+    geoSearch(q: GeoSearchQuery): Promise<GeoHit[]>;
+    /** The cell hashtag for a point — name geo keys `{cell}id` for bounded cluster search. */
+    cell(lon: number, lat: number): Promise<string>;
+    /** Bloom add — resolves 1 if newly added, 0 if probably already present. */
+    bfAdd(key: string, item: string): Promise<number>;
+    bfExists(key: string, item: string): Promise<number>;
+    cmsIncrBy(key: string, item: string, by: number): Promise<unknown>;
+    cmsQuery(key: string, item: string): Promise<number>;
+    topkAdd(key: string, ...items: string[]): Promise<unknown>;
+    topkList(key: string): Promise<string[]>;
+    tdAdd(key: string, ...values: number[]): Promise<unknown>;
+    tdQuantile(key: string, ...quantiles: number[]): Promise<number[]>;
+    /** Set `key` to `next` only if it currently equals `expected`. 1 on swap. */
+    cas(key: string, expected: string, next: string): Promise<number>;
+    caDel(key: string, expected: string): Promise<number>;
+    setMax(key: string, value: number): Promise<unknown>;
+    incrCap(key: string, by: number, cap: number): Promise<unknown>;
+    idxCreate(name: string, field: string): Promise<unknown>;
+    idxDrop(name: string): Promise<unknown>;
+    idxGet(name: string, value: string): Promise<string[]>;
+    idxRange(name: string, min: string, max: string, count?: number): Promise<string[]>;
+    /** Read changes after `offset` (needs `LOCUS_CDC_MAXLEN` retention on the server). */
+    cdcRead(offset: number, opts?: {
+        count?: number;
+        prefix?: string;
+    }): Promise<Change[]>;
+    /** Global, HLC-ordered changefeed merged across all shards. Advance `sinceHlc`. */
+    clusterCdcMerge(sinceHlc?: number, count?: number): Promise<Array<{
+        hlc: number;
+        op: string;
+        key: string;
+        value: string | null;
+    }>>;
+    /** Live changefeed over a dedicated connection. Pass a key prefix to filter. */
+    changefeed(prefix?: string): Changefeed;
+    /** Live geofence over a dedicated connection — emits enter/move/leave. */
+    geofence(lon: number, lat: number, radius: number, unit?: GeoUnit): Geofence;
+    /** Close the underlying ioredis connection. */
+    quit(): Promise<"OK">;
+}

package/dist/client.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocusClient = void 0;
+const ioredis_1 = __importDefault(require("ioredis"));
+const changefeed_1 = require("./changefeed");
+/**
+ * A Locus client. Wraps `ioredis` for every request/reply command (standard
+ * Redis ops via `.redis`, the differentiator verbs via the typed helpers here)
+ * and adds the reactive APIs — {@link changefeed} and {@link geofence} — that a
+ * plain Redis driver can't surface.
+ */
+class LocusClient {
+    constructor(options = {}) {
+        this.redis = new ioredis_1.default(options);
+        this.sub = {
+            host: options.host ?? "127.0.0.1",
+            port: options.port ?? 6379,
+            password: typeof options.password === "string" ? options.password : undefined,
+            tls: !!options.tls,
+        };
+    }
+    // ---- geo ----------------------------------------------------------------
+    /** Store a geo point, with optional inline attributes for `where` filtering. */
+    geoSet(key, lon, lat, attrs) {
+        const extra = attrs ? Object.entries(attrs).flat() : [];
+        return this.redis.call("GEOSET", key, String(lon), String(lat), ...extra);
+    }
+    /** `[lon, lat]` for a key, or null if absent. */
+    async geoPos(key) {
+        const r = (await this.redis.call("GEOPOS", key));
+        return r && r.length >= 2 ? [Number(r[0]), Number(r[1])] : null;
+    }
+    /** Distance between two geo keys in `unit` (default meters). */
+    async geoDist(a, b, unit = "m") {
+        const r = (await this.redis.call("GEODIST", a, b, unit));
+        return r == null ? null : Number(r);
+    }
+    /** Spatial search; returns parsed hits (cluster-aware — the server merges shards). */
+    async geoSearch(q) {
+        const args = [];
+        if (q.fromLonLat)
+            args.push("FROMLONLAT", String(q.fromLonLat[0]), String(q.fromLonLat[1]));
+        if (q.fromMember)
+            args.push("FROMMEMBER", q.fromMember);
+        if (q.byRadius)
+            args.push("BYRADIUS", String(q.byRadius[0]), q.byRadius[1]);
+        if (q.byBox)
+            args.push("BYBOX", String(q.byBox[0]), String(q.byBox[1]), q.byBox[2]);
+        if (q.order)
+            args.push(q.order);
+        if (q.count != null)
+            args.push("COUNT", String(q.count));
+        if (q.withCoord)
+            args.push("WITHCOORD");
+        if (q.withDist)
+            args.push("WITHDIST");
+        if (q.where)
+            for (const [f, v] of Object.entries(q.where))
+                args.push("WHERE", f, v);
+        const raw = (await this.redis.call("GEOSEARCH", ...args));
+        if (!q.withCoord && !q.withDist) {
+            return raw.map((key) => ({ key }));
+        }
+        return raw.map((row) => {
+            const hit = { key: String(row[0]) };
+            let i = 1;
+            if (q.withDist)
+                hit.dist = Number(row[i++]);
+            if (q.withCoord) {
+                const c = row[i++];
+                hit.coord = [Number(c[0]), Number(c[1])];
+            }
+            return hit;
+        });
+    }
+    /** The cell hashtag for a point — name geo keys `{cell}id` for bounded cluster search. */
+    async cell(lon, lat) {
+        return String(await this.redis.call("CLUSTER", "CELL", String(lon), String(lat)));
+    }
+    // ---- sketches -----------------------------------------------------------
+    /** Bloom add — resolves 1 if newly added, 0 if probably already present. */
+    bfAdd(key, item) {
+        return this.redis.call("BFADD", key, item);
+    }
+    bfExists(key, item) {
+        return this.redis.call("BFEXISTS", key, item);
+    }
+    cmsIncrBy(key, item, by) {
+        return this.redis.call("CMSINCRBY", key, item, String(by));
+    }
+    async cmsQuery(key, item) {
+        return Number(await this.redis.call("CMSQUERY", key, item));
+    }
+    topkAdd(key, ...items) {
+        return this.redis.call("TOPKADD", key, ...items);
+    }
+    topkList(key) {
+        return this.redis.call("TOPKLIST", key);
+    }
+    tdAdd(key, ...values) {
+        return this.redis.call("TDADD", key, ...values.map(String));
+    }
+    async tdQuantile(key, ...quantiles) {
+        const r = (await this.redis.call("TDQUANTILE", key, ...quantiles.map(String)));
+        return r.map(Number);
+    }
+    // ---- conditional writes (CAS) ------------------------------------------
+    /** Set `key` to `next` only if it currently equals `expected`. 1 on swap. */
+    cas(key, expected, next) {
+        return this.redis.call("CAS", key, expected, next);
+    }
+    caDel(key, expected) {
+        return this.redis.call("CADEL", key, expected);
+    }
+    setMax(key, value) {
+        return this.redis.call("SETMAX", key, String(value));
+    }
+    incrCap(key, by, cap) {
+        return this.redis.call("INCRCAP", key, String(by), String(cap));
+    }
+    // ---- secondary index ----------------------------------------------------
+    idxCreate(name, field) {
+        return this.redis.call("IDXCREATE", name, field);
+    }
+    idxDrop(name) {
+        return this.redis.call("IDXDROP", name);
+    }
+    idxGet(name, value) {
+        return this.redis.call("IDXGET", name, value);
+    }
+    idxRange(name, min, max, count) {
+        const extra = count != null ? ["COUNT", String(count)] : [];
+        return this.redis.call("IDXRANGE", name, min, max, ...extra);
+    }
+    // ---- changefeed: pull ---------------------------------------------------
+    /** Read changes after `offset` (needs `LOCUS_CDC_MAXLEN` retention on the server). */
+    async cdcRead(offset, opts = {}) {
+        const args = [String(offset)];
+        if (opts.count != null)
+            args.push("COUNT", String(opts.count));
+        if (opts.prefix != null)
+            args.push("PREFIX", opts.prefix);
+        const raw = (await this.redis.call("CDCREAD", ...args));
+        return raw.map((r) => ({
+            offset: Number(r[0]),
+            op: String(r[1]),
+            key: String(r[2]),
+            value: (r[3] ?? null),
+        }));
+    }
+    // ---- cluster: cross-shard changefeed -----------------------------------
+    /** Global, HLC-ordered changefeed merged across all shards. Advance `sinceHlc`. */
+    async clusterCdcMerge(sinceHlc = 0, count) {
+        const extra = count != null ? ["COUNT", String(count)] : [];
+        const raw = (await this.redis.call("CLUSTER", "CDCMERGE", String(sinceHlc), ...extra));
+        return raw.map((r) => ({
+            hlc: Number(r[0]),
+            op: String(r[1]),
+            key: String(r[2]),
+            value: (r[3] ?? null),
+        }));
+    }
+    // ---- reactive (the part a plain driver can't do) ------------------------
+    /** Live changefeed over a dedicated connection. Pass a key prefix to filter. */
+    changefeed(prefix) {
+        return new changefeed_1.Changefeed(this.sub, prefix ? ["CDCSUBSCRIBE", prefix] : ["CDCSUBSCRIBE"]);
+    }
+    /** Live geofence over a dedicated connection — emits enter/move/leave. */
+    geofence(lon, lat, radius, unit = "km") {
+        return new changefeed_1.Geofence(this.sub, lon, lat, radius, unit);
+    }
+    /** Close the underlying ioredis connection. */
+    quit() {
+        return this.redis.quit();
+    }
+}
+exports.LocusClient = LocusClient;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { LocusClient } from "./client";
+export type { LocusOptions, GeoSearchQuery, GeoUnit, GeoHit, } from "./client";
+export { Changefeed, Geofence } from "./changefeed";
+export type { SubscribeOptions, Change, GeoEvent } from "./changefeed";
+export { RespReader } from "./resp";
+export type { RespValue } from "./resp";

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RespReader = exports.Geofence = exports.Changefeed = exports.LocusClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "LocusClient", { enumerable: true, get: function () { return client_1.LocusClient; } });
+var changefeed_1 = require("./changefeed");
+Object.defineProperty(exports, "Changefeed", { enumerable: true, get: function () { return changefeed_1.Changefeed; } });
+Object.defineProperty(exports, "Geofence", { enumerable: true, get: function () { return changefeed_1.Geofence; } });
+var resp_1 = require("./resp");
+Object.defineProperty(exports, "RespReader", { enumerable: true, get: function () { return resp_1.RespReader; } });

package/dist/resp.d.ts

@@ -0,0 +1,8 @@
+export type RespValue = string | number | null | RespValue[];
+export declare class RespReader {
+    private buf;
+    /** Feed received bytes; return every complete top-level value now available. */
+    push(chunk: Buffer): RespValue[];
+    private parse;
+    private readLine;
+}

package/dist/resp.js

@@ -0,0 +1,86 @@
+"use strict";
+// A minimal, incremental RESP reader — just enough to consume the changefeed
+// push stream on a dedicated connection. The full request/reply path uses
+// ioredis; this exists only because ioredis can't surface Locus's custom push
+// frames (CDCSUBSCRIBE), which arrive as arrays of bulk strings out-of-band.
+//
+// Handles the frame types Locus can send on a subscription: simple string (+),
+// error (-), integer (:), bulk string ($), array (*), RESP3 push (>), and null.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RespReader = void 0;
+const CR = 0x0d;
+class RespReader {
+    constructor() {
+        this.buf = Buffer.alloc(0);
+    }
+    /** Feed received bytes; return every complete top-level value now available. */
+    push(chunk) {
+        this.buf = this.buf.length ? Buffer.concat([this.buf, chunk]) : chunk;
+        const out = [];
+        for (;;) {
+            const r = this.parse(0);
+            if (!r)
+                break; // incomplete — wait for more bytes
+            out.push(r.value);
+            this.buf = this.buf.subarray(r.next);
+        }
+        return out;
+    }
+    // Parse one value starting at absolute offset `i`. Returns the value and the
+    // offset just past it, or null if the buffer doesn't hold a complete value yet.
+    parse(i) {
+        if (i >= this.buf.length)
+            return null;
+        const type = this.buf[i];
+        const line = this.readLine(i + 1);
+        if (!line)
+            return null;
+        const { text, next } = line;
+        switch (type) {
+            case 0x2b: // '+' simple string
+            case 0x2d: // '-' error (surfaced as a string; callers ignore handshake noise)
+                return { value: text, next };
+            case 0x3a: // ':' integer
+                return { value: Number(text), next };
+            case 0x24: {
+                // '$' bulk string
+                const len = Number(text);
+                if (len < 0)
+                    return { value: null, next };
+                const end = next + len;
+                if (end + 2 > this.buf.length)
+                    return null; // payload + CRLF not all here
+                return { value: this.buf.toString('utf8', next, end), next: end + 2 };
+            }
+            case 0x2a: // '*' array
+            case 0x3e: {
+                // '>' RESP3 push (same framing as an array)
+                const len = Number(text);
+                if (len < 0)
+                    return { value: null, next };
+                const arr = [];
+                let pos = next;
+                for (let k = 0; k < len; k++) {
+                    const el = this.parse(pos);
+                    if (!el)
+                        return null; // a nested element is incomplete
+                    arr.push(el.value);
+                    pos = el.next;
+                }
+                return { value: arr, next: pos };
+            }
+            case 0x5f: // '_' RESP3 null
+                return { value: null, next };
+            default:
+                // Inline/unknown line — return as text so we never stall the stream.
+                return { value: text, next };
+        }
+    }
+    readLine(i) {
+        const cr = this.buf.indexOf(CR, i);
+        if (cr < 0 || cr + 1 >= this.buf.length)
+            return null; // need the '\n' too
+        return { text: this.buf.toString('utf8', i, cr), next: cr + 2 };
+    }
+}
+exports.RespReader = RespReader;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "locusdb-client",
+  "version": "0.1.0",
+  "description": "Node.js client for Locus — typed access to the differentiator verbs (geo, sketches, CAS, secondary index) plus the reactive changefeed and live geofencing that a plain Redis driver can't surface.",
+  "keywords": ["locus", "locusdb", "redis", "changefeed", "cdc", "geo", "geofence"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/intenttext/locus",
+    "directory": "clients/node"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ioredis": "^5.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}