@anysoftinc/anydb-sdk 0.1.2 → 0.3.0

package/dist/client.js

@@ -1,29 +1,61 @@
-// Core types for Datomic data model
+// AnyDB TypeScript SDK v2 - strict, no-fallback client
+// - Explicit EDN symbolic types (Keyword, Symbol, UUID)
+// - Strict SymbolicQuery API
+// - Explicit DataScript selection via storage alias (no fallback)
+// - Keywordized JS<->EDN conversion for object keys
 import { parseEDNString as parseEdn } from "edn-data";
-export const sym = (name) => ({ _type: 'symbol', value: name });
-export const uuid = (id) => ({ _type: 'uuid', value: id });
-export const kw = (name) => ({ _type: 'keyword', value: name });
-/**
- * Enhanced EDN stringifier with support for symbolic types
- */
+import { DataScriptBackend, shouldUseDataScript, isDataScriptAvailable, } from "./datascript-backend";
+export const sym = (name) => ({ _type: "symbol", value: name });
+export const uuid = (id) => ({ _type: "uuid", value: id });
+export const kw = (name) => {
+    if (typeof name !== "string" || !name) {
+        throw new QueryInputError("kw() requires a non-empty string name");
+    }
+    if (name.startsWith(":")) {
+        throw new QueryInputError("kw() expects bare keyword without leading ':'", {
+            name,
+        });
+    }
+    return {
+        _type: "keyword",
+        value: name,
+    };
+};
+// ===== Errors =====
+class AnyDBError extends Error {
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = this.constructor.name;
+    }
+}
+export class AuthError extends AnyDBError {
+}
+export class QueryInputError extends AnyDBError {
+}
+export class SchemaError extends AnyDBError {
+}
+export class TransportError extends AnyDBError {
+}
+export class ServerError extends AnyDBError {
+}
+// ===== EDN Stringifier with keywordized key handling =====
 export function stringifyEdn(obj) {
     // Handle symbolic types first
     if (typeof obj === "object" && obj !== null && "_type" in obj) {
         const typed = obj;
         switch (typed._type) {
-            case 'symbol':
+            case "symbol":
                 return typed.value; // ?e, ?id, etc.
-            case 'uuid':
+            case "uuid":
                 return `#uuid "${typed.value}"`;
-            case 'keyword':
-                return typed.value.startsWith(':') ? typed.value : `:${typed.value}`;
+            case "keyword":
+                // Ensure leading colon when emitting
+                return `:${typed.value}`;
         }
     }
     if (typeof obj === "string") {
-        // Keywords and symbols don't get quoted, strings do
-        if (obj.startsWith(":") || obj.startsWith("?")) {
-            return obj;
-        }
+        // Strings are always quoted; callers must use sym/kw for special values
         return `"${obj.replace(/"/g, '\\"')}"`;
     }
     if (typeof obj === "number")
@@ -38,360 +70,296 @@ export function stringifyEdn(obj) {
         return "[" + obj.map(stringifyEdn).join(" ") + "]";
     }
     if (typeof obj === "object") {
+        // Keywordize JS object keys by emitting them as EDN keywords
         const pairs = Object.entries(obj).map(([key, value]) => {
-            // Handle Datomic keyword keys
-            const ednKey = key.startsWith(":") ? key : `:${key}`;
+            if (key.startsWith(":")) {
+                throw new QueryInputError("Object keys representing keywords must not include a leading ':'", { key });
+            }
+            const ednKey = `:${key}`;
             return `${ednKey} ${stringifyEdn(value)}`;
         });
         return "{" + pairs.join(" ") + "}";
     }
     return String(obj);
 }
-// Main SDK Client
-export class DatomicClient {
-    constructor(config) {
-        this.config = config;
-        this.baseUrl = config.baseUrl.replace(/\/$/, ""); // Remove trailing slash
-    }
-    // Normalize EDN parsed values to JS-friendly shapes
-    normalizeEdn(value) {
-        if (value === null || value === undefined)
-            return value;
-        // edn-data often wraps symbols/keywords/strings as { key: '...' }
-        if (typeof value === 'object' && value && typeof value.key === 'string') {
-            return value.key;
+// Normalize edn-data parsed value into JS with keywordized keys (no leading colon)
+function normalizeEdn(value) {
+    if (value === null || value === undefined)
+        return value;
+    // Preserve native Date instances returned by the parser
+    if (value instanceof Date)
+        return value;
+    // edn-data often wraps keywords/symbols/strings as { key: '...' } or { sym: '...' }
+    if (typeof value === "object" && value) {
+        if (typeof value.key === "string") {
+            const key = value.key; // e.g., ":db/ident"
+            return key.startsWith(":") ? key.slice(1) : key;
+        }
+        if (typeof value.sym === "string") {
+            return value.sym;
         }
-        // Sets -> Arrays
         if (value instanceof Set) {
-            return Array.from(value, (v) => this.normalizeEdn(v));
+            return Array.from(value, (v) => normalizeEdn(v));
         }
-        // edn-data set representation: { set: [...] }
-        if (typeof value === 'object' && value && Array.isArray(value.set)) {
-            return value.set.map((v) => this.normalizeEdn(v));
+        if (Array.isArray(value.set)) {
+            return value.set.map((v) => normalizeEdn(v));
         }
-        // edn-data map representation: { map: [[k,v] ...] }
-        if (typeof value === 'object' && value && Array.isArray(value.map)) {
+        if (Array.isArray(value.map)) {
             const out = {};
             for (const [k, v] of value.map) {
-                const keyNorm = this.normalizeEdn(k);
-                const keyStr = typeof keyNorm === 'string' ? keyNorm : String(keyNorm);
-                out[keyStr] = this.normalizeEdn(v);
+                const kNorm = normalizeEdn(k);
+                const kStr = typeof kNorm === "string" ? kNorm : String(kNorm);
+                const bareKey = kStr.startsWith(":") ? kStr.slice(1) : kStr;
+                out[bareKey] = normalizeEdn(v);
             }
             return out;
         }
-        // Arrays
-        if (Array.isArray(value)) {
-            return value.map((v) => this.normalizeEdn(v));
+    }
+    if (Array.isArray(value))
+        return value.map((v) => normalizeEdn(v));
+    // Tagged values
+    if (typeof value === "object" &&
+        value &&
+        value.tag === "inst" &&
+        typeof value.val === "string") {
+        const d = new Date(value.val);
+        return isNaN(d.getTime()) ? value.val : d;
+    }
+    if (typeof value === "object" &&
+        value &&
+        value.tag === "uuid" &&
+        typeof value.val === "string") {
+        return { _type: "uuid", value: value.val };
+    }
+    if (typeof value === "object") {
+        const out = Array.isArray(value) ? [] : {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = normalizeEdn(v);
         }
-        // Objects: attempt to descend shallowly
-        if (typeof value === 'object') {
-            // Convert common UUID representations to a consistent shape
-            if (value.tag === 'uuid' && typeof value.val === 'string') {
-                return { _type: 'uuid', value: value.val };
-            }
-            if (value.type === 'uuid' && typeof value.value === 'string') {
-                return value; // already in {_type:'uuid', value}
-            }
-            // Convert inst tag to Date
-            if (value.tag === 'inst' && typeof value.val === 'string') {
-                const d = new Date(value.val);
-                return isNaN(d.getTime()) ? value.val : d;
-            }
-            const out = Array.isArray(value) ? [] : {};
-            for (const [k, v] of Object.entries(value)) {
-                out[k] = this.normalizeEdn(v);
+        return out;
+    }
+    return value;
+}
+// ===== Validation =====
+function isKeyword(v) {
+    return typeof v === "object" && v !== null && v._type === "keyword";
+}
+function isSymbol(v) {
+    return typeof v === "object" && v !== null && v._type === "symbol";
+}
+function validateSymbolicQuery(q) {
+    if (!q ||
+        typeof q !== "object" ||
+        !Array.isArray(q.find) ||
+        !Array.isArray(q.where)) {
+        throw new QueryInputError("Invalid query object: requires { find: [], where: [] }");
+    }
+    // Enforce attribute positions to be Keyword in where clauses when pattern triples
+    for (let i = 0; i < q.where.length; i++) {
+        const clause = q.where[i];
+        if (Array.isArray(clause) &&
+            clause.length >= 3 &&
+            !Array.isArray(clause[0])) {
+            const attr = clause[1];
+            if (!isKeyword(attr)) {
+                throw new QueryInputError("Attribute position in where clause must be a Keyword", {
+                    clauseIndex: i,
+                    clause,
+                });
             }
-            return out;
         }
-        return value;
     }
-    async request(endpoint, options = {}) {
-        const url = `${this.baseUrl}${endpoint}`;
-        // Convert body to EDN if present
-        const processedOptions = { ...options };
-        if (processedOptions.body && typeof processedOptions.body !== "string") {
-            processedOptions.body = stringifyEdn(processedOptions.body);
-        }
-        const response = await fetch(url, {
-            headers: {
-                "Content-Type": "application/edn",
-                Accept: "application/edn",
-                ...this.config.headers,
-                ...options.headers,
-            },
-            ...processedOptions,
-        });
-        if (!response.ok) {
-            throw new Error(`Datomic API error: ${response.status} ${response.statusText}`);
+}
+// ===== Root HTTP Client =====
+export class DatomicClient {
+    constructor(config) {
+        this.config = config;
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.fetchImpl = (config.fetchImpl ||
+            globalThis.fetch);
+        if (!this.fetchImpl) {
+            throw new TransportError("fetch implementation is required in this environment");
         }
-        // Parse EDN response
-        const responseText = await response.text();
-        const parsed = parseEdn(responseText);
-        return this.normalizeEdn(parsed);
     }
-    // List databases in a storage
-    async listDatabases(storageAlias) {
-        return this.request(`/data/${storageAlias}/`);
+    async authHeader() {
+        let token = this.config.authToken;
+        if (!token && this.config.getAuthToken) {
+            const s = this.config.getAuthToken();
+            token = typeof s === "string" ? s : await s;
+        }
+        if (!token) {
+            throw new AuthError("Missing signing secret (provide authentication jwt or getAuthToken in client config)");
+        }
+        return { Authorization: `Bearer ${token}` };
     }
-    // Create database
-    async createDatabase(storageAlias, dbName) {
-        return this.request(`/data/${storageAlias}/`, {
+    async request(endpoint, body) {
+        const url = `${this.baseUrl}${endpoint}`;
+        const headers = {
+            "Content-Type": "application/edn",
+            Accept: "application/edn",
+            ...(this.config.headers || {}),
+            ...(await this.authHeader()),
+        };
+        const res = await this.fetchImpl(url, {
             method: "POST",
-            body: { ":db-name": dbName },
-        });
-    }
-    // Delete database
-    async deleteDatabase(storageAlias, dbName) {
-        return this.request(`/data/${storageAlias}/${dbName}/`, {
-            method: "DELETE",
+            headers,
+            body: body === undefined ? undefined : stringifyEdn(body),
         });
+        if (!res.ok) {
+            let serverBody = undefined;
+            try {
+                const txt = await res.text();
+                serverBody = normalizeEdn(parseEdn(txt));
+            }
+            catch (_) {
+                // ignore parse errors
+            }
+            throw new ServerError(`HTTP ${res.status} ${res.statusText}`, {
+                status: res.status,
+                endpoint,
+                serverBody,
+            });
+        }
+        const text = await res.text();
+        const parsed = parseEdn(text);
+        return normalizeEdn(parsed);
     }
-    // Transaction operations
+    // Low-level endpoints (path-style)
     async transact(storageAlias, dbName, txData) {
+        // Basic schema validation: txData must be an array of entity maps or operation vectors
+        if (!Array.isArray(txData)) {
+            throw new SchemaError("txData must be an array of entities/ops");
+        }
         return this.request(`/data/${storageAlias}/${dbName}/`, {
-            method: "POST",
-            body: { ":tx-data": txData },
+            "tx-data": txData,
         });
     }
-    // Retrieve database info
-    async databaseInfo(storageAlias, dbName, basisT = "-") {
-        return this.request(`/data/${storageAlias}/${dbName}/${basisT}/`);
-    }
-    // Datoms operations
-    async datoms(storageAlias, dbName, basisT, options) {
-        const params = new URLSearchParams();
-        // Required parameter
-        params.append("index", options.index);
-        // Optional parameters
-        if (options.e !== undefined)
-            params.append("e", String(options.e));
-        if (options.a !== undefined)
-            params.append("a", String(options.a));
-        if (options.v !== undefined)
-            params.append("v", String(options.v));
-        if (options.start !== undefined)
-            params.append("start", String(options.start));
-        if (options.end !== undefined)
-            params.append("end", String(options.end));
-        if (options.limit !== undefined)
-            params.append("limit", String(options.limit));
-        if (options.offset !== undefined)
-            params.append("offset", String(options.offset));
-        if (options["as-of"] !== undefined)
-            params.append("as-of", String(options["as-of"]));
-        if (options.since !== undefined)
-            params.append("since", String(options.since));
-        if (options.history !== undefined)
-            params.append("history", String(options.history));
-        return this.request(`/data/${storageAlias}/${dbName}/${basisT}/datoms?${params.toString()}`);
-    }
-    // Entity operations
-    async entity(storageAlias, dbName, basisT, entityId, options) {
-        const params = new URLSearchParams();
-        params.append("e", String(entityId));
-        if (options?.["as-of"] !== undefined)
-            params.append("as-of", String(options["as-of"]));
-        if (options?.since !== undefined)
-            params.append("since", String(options.since));
-        return this.request(`/data/${storageAlias}/${dbName}/${basisT}/entity?${params.toString()}`);
-    }
-    // Query operations (GET version for simple queries)
-    async queryGet(query, args, options) {
-        const params = new URLSearchParams();
-        params.append("q", stringifyEdn(query));
-        params.append("args", stringifyEdn(args));
-        if (options?.limit !== undefined)
-            params.append("limit", String(options.limit));
-        if (options?.offset !== undefined)
-            params.append("offset", String(options.offset));
-        return this.request(`/api/query?${params.toString()}`);
-    }
-    // Query operations (POST version for complex queries)
-    async query(query, args, options) {
+    async querySymbolic(q, args = [], options) {
+        validateSymbolicQuery(q);
         const body = {
-            ":q": query,
-            ":args": args,
+            q: [
+                kw("find"),
+                ...q.find,
+                ...(q.in && q.in.length ? [kw("in"), ...q.in] : []),
+                kw("where"),
+                ...q.where,
+            ],
+            args,
         };
         if (options?.limit !== undefined)
-            body[":limit"] = options.limit;
+            body["limit"] = options.limit;
         if (options?.offset !== undefined)
-            body[":offset"] = options.offset;
-        const res = await this.request("/api/query", {
-            method: "POST",
-            body: body,
-        });
-        // Ensure result is array of rows, not Set
-        if (res instanceof Set) {
-            return Array.from(res);
-        }
-        return res;
+            body["offset"] = options.offset;
+        return this.request(`/api/query`, body);
     }
-    // Symbolic query operations
-    async querySymbolic(query, args = [], options) {
-        // Convert symbolic query to EDN vector format
-        const ednQuery = [":find", ...query.find];
-        if (query.in && query.in.length > 0) {
-            ednQuery.push(":in", ...query.in);
-        }
-        ednQuery.push(":where", ...query.where);
-        return this.query(ednQuery, args, options);
-    }
-    // Server-Sent Events for transaction reports
     subscribeToEvents(storageAlias, dbName, onEvent, onError) {
-        const eventSource = new EventSource(`${this.baseUrl}/events/${storageAlias}/${dbName}`);
-        eventSource.onmessage = onEvent;
-        if (onError)
-            eventSource.onerror = onError;
-        return eventSource;
-    }
-}
-// Utility functions for common Datomic operations
-export class DatomicUtils {
-    static tempId(partition = "db.part/user") {
-        return `tempid:${partition}:${Math.random().toString(36).substr(2, 9)}`;
-    }
-    static keyword(namespace, name) {
-        return `:${namespace}/${name}`;
-    }
-    static createEntity(attributes, tempId) {
-        const id = tempId || this.tempId();
-        return Object.entries(attributes).map(([attr, value]) => ({
-            "db/id": id,
-            [attr]: value,
-        }));
-    }
-    static retractEntity(entityId) {
-        return [[":db/retractEntity", entityId]];
-    }
-    static retractAttribute(entityId, attribute, value) {
-        if (value !== undefined) {
-            return [[":db/retract", entityId, attribute, value]];
+        const factory = this.config.eventSourceFactory || globalThis.EventSource;
+        if (!factory) {
+            throw new TransportError("EventSource not available. Provide eventSourceFactory in client config for Node.");
         }
-        return [[":db/retract", entityId, attribute]];
-    }
-    static addAttribute(entityId, attribute, value) {
-        return [[":db/add", entityId, attribute, value]];
-    }
-}
-export class SchemaBuilder {
-    static attribute(def) {
-        return {
-            "db/id": DatomicUtils.tempId(),
-            ...def,
-        };
-    }
-    static enum(ident, doc) {
-        const enumDef = {
-            "db/id": DatomicUtils.tempId(),
-            ":db/ident": ident,
-        };
-        if (doc) {
-            enumDef[":db/doc"] = doc;
-        }
-        return enumDef;
-    }
-}
-// EDN template literal for natural Datalog queries
-export function edn(strings, ...values) {
-    // Combine template strings and interpolated values
-    let ednString = '';
-    for (let i = 0; i < strings.length; i++) {
-        ednString += strings[i];
-        if (i < values.length) {
-            const value = values[i];
-            // Convert interpolated values to EDN strings
-            ednString += stringifyEdn(value);
-        }
-    }
-    // Use the proper EDN parser
-    const parsed = parseEdn(ednString);
-    // Apply normalization similar to the client's normalizeEdn method
-    return normalizeEdnForQuery(parsed);
-}
-function normalizeEdnForQuery(value) {
-    if (value === null || value === undefined)
-        return value;
-    // Handle edn-data keyword representations: {key: "find"} -> ":find"
-    if (typeof value === 'object' && value && typeof value.key === 'string') {
-        const key = value.key;
-        return key.startsWith(':') ? key : `:${key}`;
-    }
-    // Handle edn-data symbol representations: {sym: "?e"} -> "?e"  
-    if (typeof value === 'object' && value && typeof value.sym === 'string') {
-        return value.sym;
-    }
-    // Handle edn-data list representations: {list: [...]} -> [...]
-    if (typeof value === 'object' && value && Array.isArray(value.list)) {
-        return value.list.map((v) => normalizeEdnForQuery(v));
-    }
-    // Sets -> Arrays  
-    if (value instanceof Set) {
-        return Array.from(value, (v) => normalizeEdnForQuery(v));
-    }
-    // edn-data set representation: { set: [...] }
-    if (typeof value === 'object' && value && Array.isArray(value.set)) {
-        return value.set.map((v) => normalizeEdnForQuery(v));
-    }
-    // Arrays
-    if (Array.isArray(value)) {
-        return value.map((v) => normalizeEdnForQuery(v));
-    }
-    // Convert common UUID representations
-    if (typeof value === 'object' && value && value.tag === 'uuid' && typeof value.val === 'string') {
-        return { _type: 'uuid', value: value.val };
+        const url = `${this.baseUrl}/events/${storageAlias}/${dbName}`;
+        const es = new factory(url);
+        es.onmessage = onEvent;
+        if (onError)
+            es.onerror = onError;
+        return es;
     }
-    return value;
 }
-// Convenience class for working with a specific database
-export class DatomicDatabase {
+// ===== Convenience wrapper for a specific database =====
+export class AnyDBClient {
     constructor(client, storageAlias, dbName) {
         this.client = client;
         this.storageAlias = storageAlias;
         this.dbName = dbName;
     }
+    async info() {
+        if (shouldUseDataScript(this.storageAlias)) {
+            const backend = new DataScriptBackend(this.storageAlias, this.dbName);
+            return backend.databaseInfo();
+        }
+        // Exercise connectivity/auth via a trivial query; propagate errors to caller.
+        const q = { find: [sym("?e")], where: [[sym("?e"), kw("db/id"), 0]] };
+        await this.query(q);
+        return { "basis-t": -1, "db/alias": `${this.storageAlias}/${this.dbName}` };
+    }
     async transact(txData) {
+        if (shouldUseDataScript(this.storageAlias)) {
+            const backend = new DataScriptBackend(this.storageAlias, this.dbName);
+            return backend.transact(txData);
+        }
         return this.client.transact(this.storageAlias, this.dbName, txData);
     }
-    async info(basisT = "-") {
-        return this.client.databaseInfo(this.storageAlias, this.dbName, basisT);
-    }
-    async datoms(index, basisT = "-", options) {
-        return this.client.datoms(this.storageAlias, this.dbName, basisT, {
-            index,
-            ...options,
-        });
-    }
-    async entity(entityId, basisT = "-", options) {
-        return this.client.entity(this.storageAlias, this.dbName, basisT, entityId, options);
-    }
-    async query(query, ...args) {
+    async query(q, ...args) {
+        if (shouldUseDataScript(this.storageAlias)) {
+            const backend = new DataScriptBackend(this.storageAlias, this.dbName);
+            validateSymbolicQuery(q);
+            const ednQuery = [
+                kw("find"),
+                ...q.find,
+                ...(q.in && q.in.length ? [kw("in"), ...q.in] : []),
+                kw("where"),
+                ...q.where,
+            ];
+            return backend.query(ednQuery, ...args);
+        }
+        // Server path: use /api/query with db descriptor as first arg
         const dbDescriptor = {
             "db/alias": `${this.storageAlias}/${this.dbName}`,
         };
-        return this.client.query(query, [dbDescriptor, ...args]);
+        return this.client.querySymbolic(q, [dbDescriptor, ...args]);
     }
-    async querySymbolic(query, ...args) {
-        const dbDescriptor = {
-            "db/alias": `${this.storageAlias}/${this.dbName}`,
+    async entity(entityId, basisT = "-", options) {
+        if (shouldUseDataScript(this.storageAlias)) {
+            const backend = new DataScriptBackend(this.storageAlias, this.dbName);
+            return backend.entity(entityId);
+        }
+        // Use the query API to retrieve entity via pull
+        const q = {
+            find: [[sym("pull"), sym("?e"), [kw("db/id")]]],
+            where: [[sym("?e"), kw("db/id"), entityId]],
         };
-        return this.client.querySymbolic(query, [dbDescriptor, ...args]);
+        const rows = await this.query(q);
+        const first = Array.isArray(rows) ? rows[0]?.[0] : null;
+        return first || { "db/id": entityId };
+    }
+    async datoms(index, options = {}) {
+        if (shouldUseDataScript(this.storageAlias)) {
+            const backend = new DataScriptBackend(this.storageAlias, this.dbName);
+            return backend.datoms(index, {
+                e: options.e,
+                a: options.a,
+                v: options.v,
+                limit: options.limit,
+                offset: options.offset,
+            });
+        }
+        // Server exposes datoms via query; implement minimal AVET example
+        const clauses = [];
+        const e = options.e !== undefined ? options.e : sym("?e");
+        const a = options.a !== undefined ? kw(options.a) : sym("?a");
+        const v = options.v !== undefined ? options.v : sym("?v");
+        clauses.push([e, a, v]);
+        const q = { find: [e, a, v], where: clauses };
+        const rows = await this.query(q);
+        return rows.map((r) => ({ e: r[0], a: r[1], v: r[2], tx: 0, added: true }));
     }
     subscribeToEvents(onEvent, onError) {
         return this.client.subscribeToEvents(this.storageAlias, this.dbName, onEvent, onError);
     }
 }
-// Factory functions
+// ===== Factories =====
 export function createDatomicClient(config) {
     return new DatomicClient(config);
 }
-export function createDatomicDatabase(client, storageAlias, dbName) {
-    return new DatomicDatabase(client, storageAlias, dbName);
+export function createAnyDBClient(client, storageAlias, dbName) {
+    return new AnyDBClient(client, storageAlias, dbName);
 }
-// Small helpers
+// Convenience
 export function pluckFirstColumn(rows) {
     if (!Array.isArray(rows))
         return [];
     return rows.map((r) => (Array.isArray(r) ? r[0] : r));
 }
-// Export everything
+// Re-export DataScript helpers for consumers that need feature-detection
+export { shouldUseDataScript, isDataScriptAvailable };
 export default DatomicClient;