camusdb 0.1.0

package/dist/values/uuid.js

@@ -0,0 +1,76 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * The three forms a CamusDB UUID takes, and the conversions between them.
+ *
+ * - The canonical string, `550e8400-e29b-41d4-a716-446655440000`. This is what the driver hands a
+ *   caller, and what a caller passes as a parameter.
+ * - 16 big-endian bytes (RFC 4122 byte order). This is the gRPC wire form.
+ * - Two big-endian 64-bit halves, high then low. This is the REST wire form and the shape the
+ *   server's own value type holds.
+ */
+const HEX = '0123456789abcdef';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** True when `value` is a canonical hyphenated UUID string. Matching ignores case. */
+export function isUuid(value) {
+    return UUID_PATTERN.test(value);
+}
+/** The 16 big-endian bytes of a canonical UUID string. */
+export function uuidToBytes(uuid) {
+    const hex = uuid.replaceAll('-', '');
+    if (hex.length !== 32) {
+        throw new TypeError(`'${uuid}' is not a UUID: a UUID has 32 hexadecimal digits.`);
+    }
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+        const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte)) {
+            throw new TypeError(`'${uuid}' is not a UUID: it holds a character that is not hexadecimal.`);
+        }
+        bytes[i] = byte;
+    }
+    return bytes;
+}
+/** The canonical string for 16 big-endian bytes. */
+export function bytesToUuid(bytes) {
+    if (bytes.length !== 16) {
+        throw new TypeError(`A UUID is 16 bytes; got ${String(bytes.length)}.`);
+    }
+    let out = '';
+    for (let i = 0; i < 16; i++) {
+        if (i === 4 || i === 6 || i === 8 || i === 10)
+            out += '-';
+        const byte = bytes[i];
+        out += HEX[byte >> 4] + HEX[byte & 0x0f];
+    }
+    return out;
+}
+/** The two big-endian 64-bit halves of a canonical UUID string. */
+export function uuidToHalves(uuid) {
+    return bytesToHalves(uuidToBytes(uuid));
+}
+/** The two big-endian 64-bit halves of 16 bytes. */
+export function bytesToHalves(bytes) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    return {
+        high: view.getBigInt64(0, false),
+        low: view.getBigInt64(8, false),
+    };
+}
+/** The 16 big-endian bytes of two 64-bit halves. */
+export function halvesToBytes(high, low) {
+    const bytes = new Uint8Array(16);
+    const view = new DataView(bytes.buffer);
+    view.setBigInt64(0, BigInt.asIntN(64, high), false);
+    view.setBigInt64(8, BigInt.asIntN(64, low), false);
+    return bytes;
+}
+/** The canonical string for two 64-bit halves. */
+export function halvesToUuid(high, low) {
+    return bytesToUuid(halvesToBytes(high, low));
+}
+//# sourceMappingURL=uuid.js.map

package/dist/values/uuid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.js","sourceRoot":"","sources":["../../src/values/uuid.ts"],"names":[],"mappings":"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"}

package/dist/vector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+/**
+ * Reads and writes the byte layout CamusDB stores an embedding in.
+ *
+ * A vector is a `bytes` column holding tightly packed little-endian float32 elements with no
+ * header, so the byte count is always four times the number of dimensions. There is no separate
+ * vector column type: a vector is bytes, and these functions are the two ends of that layout.
+ */
+export declare const CamusVector: {
+    /** The byte payload for a vector. */
+    readonly toBytes: (vector: ArrayLike<number>) => Uint8Array;
+    /** The elements of a stored vector. */
+    readonly toFloats: (bytes: Uint8Array) => Float32Array;
+    /**
+     * How many elements a stored vector holds.
+     *
+     * @throws {CamusError} `CADB0410` when the byte count is not a multiple of four.
+     */
+    readonly dimensions: (bytes: Uint8Array) => number;
+};
+//# sourceMappingURL=vector.d.ts.map

package/dist/vector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.d.ts","sourceRoot":"","sources":["../src/vector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;IACtB,qCAAqC;+BACrB,SAAS,CAAC,MAAM,CAAC,KAAG,UAAU;IAW9C,uCAAuC;+BACvB,UAAU,KAAG,YAAY;IAYzC;;;;OAIG;iCACe,UAAU,KAAG,MAAM;CAU7B,CAAC"}

package/dist/vector.js

@@ -0,0 +1,48 @@
+/**
+ * This file is part of CamusDB
+ *
+ * For the full copyright and license information, please view the LICENSE.txt
+ * file that was distributed with this source code.
+ */
+import { CamusError } from './errors.js';
+import { CamusErrorCode } from './error-codes.js';
+/**
+ * Reads and writes the byte layout CamusDB stores an embedding in.
+ *
+ * A vector is a `bytes` column holding tightly packed little-endian float32 elements with no
+ * header, so the byte count is always four times the number of dimensions. There is no separate
+ * vector column type: a vector is bytes, and these functions are the two ends of that layout.
+ */
+export const CamusVector = {
+    /** The byte payload for a vector. */
+    toBytes(vector) {
+        const bytes = new Uint8Array(vector.length * 4);
+        const view = new DataView(bytes.buffer);
+        for (let i = 0; i < vector.length; i++) {
+            view.setFloat32(i * 4, vector[i], true);
+        }
+        return bytes;
+    },
+    /** The elements of a stored vector. */
+    toFloats(bytes) {
+        const dimensions = CamusVector.dimensions(bytes);
+        const vector = new Float32Array(dimensions);
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        for (let i = 0; i < dimensions; i++) {
+            vector[i] = view.getFloat32(i * 4, true);
+        }
+        return vector;
+    },
+    /**
+     * How many elements a stored vector holds.
+     *
+     * @throws {CamusError} `CADB0410` when the byte count is not a multiple of four.
+     */
+    dimensions(bytes) {
+        if (bytes.length % 4 !== 0) {
+            throw new CamusError(CamusErrorCode.InvalidVector, `A vector's byte count must be a multiple of 4; got ${String(bytes.length)}.`);
+        }
+        return bytes.length / 4;
+    },
+};
+//# sourceMappingURL=vector.js.map

package/dist/vector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector.js","sourceRoot":"","sources":["../src/vector.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,qCAAqC;IACrC,OAAO,CAAC,MAAyB;QAC/B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAExC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAW,EAAE,IAAI,CAAC,CAAC;QACpD,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED,uCAAuC;IACvC,QAAQ,CAAC,KAAiB;QACxB,MAAM,UAAU,GAAG,WAAW,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,UAAU,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAE5E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;YACpC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,KAAiB;QAC1B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,UAAU,CAClB,cAAc,CAAC,aAAa,EAC5B,sDAAsD,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAC9E,CAAC;QACJ,CAAC;QAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IAC1B,CAAC;CACO,CAAC"}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "camusdb",
+  "version": "0.1.0",
+  "description": "CamusDB connector for Node.js \u2014 REST and gRPC transports, transactions, prepared statements, learned routing, and online backups.",
+  "license": "MIT",
+  "author": "CamusDB",
+  "homepage": "https://github.com/camusdb/camusdb-ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/camusdb/camusdb-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/camusdb/camusdb-ts/issues"
+  },
+  "keywords": [
+    "camusdb",
+    "database",
+    "sql",
+    "driver",
+    "connector",
+    "grpc"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "proto",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"{src,test,examples}/**/*.ts\"",
+    "format:check": "prettier --check \"{src,test,examples}/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:live": "vitest run --config vitest.live.config.ts",
+    "prepublishOnly": "npm run lint && npm run format:check && npm run typecheck && npm test",
+    "prepack": "npm run clean && npm run build"
+  },
+  "peerDependencies": {
+    "@grpc/grpc-js": "^1.12.0",
+    "@grpc/proto-loader": "^0.7.13"
+  },
+  "peerDependenciesMeta": {
+    "@grpc/grpc-js": {
+      "optional": true
+    },
+    "@grpc/proto-loader": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.15.0",
+    "@grpc/grpc-js": "^1.12.2",
+    "@grpc/proto-loader": "^0.7.13",
+    "@types/node": "^22.9.0",
+    "@vitest/coverage-v8": "^2.1.5",
+    "eslint": "^9.15.0",
+    "prettier": "^3.3.3",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.15.0",
+    "vitest": "^2.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}