@anysoftinc/anydb-sdk 0.1.2 → 0.4.0

package/README.md

@@ -11,35 +11,43 @@ npm install @anysoftinc/anydb-sdk
 ## Quick Start
 
 ```typescript
-import { DatomicClient, createDatomicDatabase } from '@anysoftinc/anydb-sdk';
+import {
+  DatomicClient,
+  createAnyDBClient,
+  kw,
+  sym,
+  uuid,
+} from "@anysoftinc/anydb-sdk";
 
 // Create a client
 const client = new DatomicClient({
-  baseUrl: 'http://localhost:4000'
+  baseUrl: "http://localhost:4000",
+  getAuthToken: () => process.env.ANYDB_TOKEN!,
 });
 
 // Create a database wrapper for convenience
-const db = createDatomicDatabase(client, 'storage-alias', 'db-name');
+const db = createAnyDBClient(client, "sql", "db-name");
 
-// Query the database
-const results = await db.query([
-  ':find', '?e', '?name',
-  ':where', ['?e', ':db/ident', '?name']
-]);
+// Symbolic query
+const query = {
+  find: [[sym("pull"), sym("?e"), [kw("db/id"), kw("person/name")]]],
+  where: [[sym("?e"), kw("person/name"), "John Doe"]],
+};
+const rows = await db.query(query);
 
-// Execute a transaction
-const txResult = await db.transact([
+// Execute a transaction (keywordized keys, kw()/uuid() for values)
+await db.transact([
   {
-    'db/id': 'tempid',
-    ':person/name': 'John Doe',
-    ':person/email': 'john@example.com'
-  }
+    ["person/id"]: uuid("550e8400-e29b-41d4-a716-446655440000"),
+    ["person/name"]: "John Doe",
+  },
 ]);
 ```
 
 ## Core Features
 
 ### Database Operations
+
 - **Database Management** - Create, list, and delete databases
 - **Transactions** - Execute database transactions
 - **Queries** - Execute Datalog queries with full EDN support
@@ -48,176 +56,109 @@ const txResult = await db.transact([
 
 ### Query Types
 
-#### Traditional Array-based Queries
-```typescript
-const query = [
-  ':find', '?e', '?name',
-  ':where', ['?e', ':person/name', '?name']
-];
-const results = await db.query(query);
-```
+Traditional array-based queries are not supported in v2.
 
 #### Symbolic Queries (Type-safe)
+
 ```typescript
-import { sym, kw } from '@anysoftinc/anydb-sdk';
+import { sym, kw } from "@anysoftinc/anydb-sdk";
 
 const query = {
-  find: [sym('?e'), sym('?name')],
-  where: [
-    [sym('?e'), kw(':person/name'), sym('?name')]
-  ]
+  find: [sym("?e"), sym("?name")],
+  where: [[sym("?e"), kw("person/name"), sym("?name")]],
 };
-const results = await db.querySymbolic(query);
+const results = await db.query(query);
 ```
 
-#### Enhanced Query Builder
-
-The QueryBuilder provides a type-safe, fluent API for constructing Datalog queries:
-
-```typescript
-import { QueryBuilder, kw } from '@anysoftinc/anydb-sdk';
-
-// Basic entity-attribute-value query
-const basicQuery = new QueryBuilder()
-  .find('?e', '?name')
-  .where({ entity: '?e', attribute: kw(':person/name'), value: '?name' })
-  .build();
-
-// Fluent entity-based building
-const fluentQuery = new QueryBuilder()
-  .find('?e', '?name')
-  .entity('?e').hasAttribute(kw(':person/name')).withValue('?name')
-  .build();
-
-// Helper methods for common patterns
-const entitiesWithName = new QueryBuilder()
-  .findEntitiesWith(kw(':person/name'))
-  .build();
-
-// Aggregation queries
-const personCount = new QueryBuilder()
-  .count('?e')
-  .where({ entity: '?e', attribute: kw(':person/name'), value: '?name' })
-  .build();
-
-// Multiple aggregations
-const stats = new QueryBuilder()
-  .count('?e')
-  .avg('?age')
-  .where({ entity: '?e', attribute: kw(':person/name'), value: '?name' })
-  .where({ entity: '?e', attribute: kw(':person/age'), value: '?age' })
-  .build();
-
-// Input parameters and with clauses
-const parameterizedQuery = new QueryBuilder()
-  .find('?e')
-  .in('$', '?minAge')
-  .with('?tx')
-  .where({ entity: '?e', attribute: kw(':person/age'), value: '?age' })
-  .build();
-
-// Direct execution
-const results = await new QueryBuilder()
-  .find('?e', '?name')
-  .entity('?e').hasAttribute(kw(':person/name')).withValue('?name')
-  .execute(db);
-```
+QueryBuilder has been removed in v2.
 
 **QueryBuilder Benefits:**
+
 - **Type Safety**: All attributes use proper `Keyword` objects with `kw()`
-- **IntelliSense**: Full autocomplete for methods and parameters  
+- **IntelliSense**: Full autocomplete for methods and parameters
 - **Structured Queries**: No string concatenation or EDN parsing errors
 - **Fluent API**: Chain methods for readable query construction
 - **Aggregations**: Built-in support for count, sum, avg, min, max
 - **Direct Execution**: Execute queries directly from the builder
 
 ### Temporal Queries
+
 ```typescript
 // As-of queries
-const pastResults = await client.query(query, [{ 
-  'db/alias': 'storage/db',
-  'as-of': 1000 
-}]);
+const pastResults = await client.query(query, [
+  {
+    "db/alias": "storage/db",
+    "as-of": 1000,
+  },
+]);
 
-// Since queries  
-const recentResults = await client.query(query, [{ 
-  'db/alias': 'storage/db',
-  since: 1000 
-}]);
+// Since queries
+const recentResults = await client.query(query, [
+  {
+    "db/alias": "storage/db",
+    since: 1000,
+  },
+]);
 
 // History queries
-const allHistory = await client.query(query, [{ 
-  'db/alias': 'storage/db',
-  history: true 
-}]);
+const allHistory = await client.query(query, [
+  {
+    "db/alias": "storage/db",
+    history: true,
+  },
+]);
 ```
 
-### Schema Definition
-```typescript
-import { SchemaBuilder, DatomicUtils } from '@anysoftinc/anydb-sdk';
-
-// Define attributes
-const personNameAttr = SchemaBuilder.attribute({
-  ':db/ident': ':person/name',
-  ':db/valueType': ':db.type/string',
-  ':db/cardinality': ':db.cardinality/one',
-  ':db/index': true,
-  ':db/doc': 'Person name'
-});
+SchemaBuilder and DatomicUtils have been removed in v2. Use plain tx maps with keywordized keys and kw()/uuid() for values.
 
-// Define enums
-const genderEnum = SchemaBuilder.enum(':person.gender/male');
+### Utility Functions
 
-// Install schema
-await db.transact([personNameAttr, genderEnum]);
-```
+Utility helpers for tempids and entity builders were removed in v2.
 
-### Utility Functions
-```typescript
-import { DatomicUtils } from '@anysoftinc/anydb-sdk';
+### Idempotent Schema Install
 
-// Generate temp IDs
-const tempId = DatomicUtils.tempId();
+Use `ensureAttributes(db, schemaEntities)` to install attribute idents exactly once per database alias. It checks which idents already exist and only transacts the missing ones.
 
-// Create entities
-const personEntity = DatomicUtils.createEntity({
-  ':person/name': 'Jane Doe',
-  ':person/email': 'jane@example.com'
-});
+```ts
+import { ensureAttributes, kw } from "@anysoftinc/anydb-sdk";
 
-// Retract data
-const retraction = DatomicUtils.retractEntity(12345);
+await ensureAttributes(db, [
+  { "db/ident": kw("person/name"), "db/valueType": kw("db.type/string"), "db/cardinality": kw("db.cardinality/one") },
+  { "db/ident": kw("person/age"),  "db/valueType": kw("db.type/long"),   "db/cardinality": kw("db.cardinality/one") },
+]);
 ```
 
 ## Advanced Features
 
 ### EDN Data Types
+
 The SDK provides full support for Datomic's EDN data types:
 
 ```typescript
-import { sym, kw, uuid } from '@anysoftinc/anydb-sdk';
+import { sym, kw, uuid } from "@anysoftinc/anydb-sdk";
 
 // Symbols for query variables
-const entityVar = sym('?e');
+const entityVar = sym("?e");
 
 // Keywords for attributes
-const nameAttr = kw(':person/name');
+const nameAttr = kw("person/name");
 
 // UUIDs
-const entityId = uuid('550e8400-e29b-41d4-a716-446655440000');
+const entityId = uuid("550e8400-e29b-41d4-a716-446655440000");
 ```
 
 ### Event Streaming
+
 Subscribe to transaction reports via Server-Sent Events:
 
 ```typescript
 const eventSource = db.subscribeToEvents(
   (event) => {
     const txData = JSON.parse(event.data);
-    console.log('Transaction:', txData);
+    console.log("Transaction:", txData);
   },
   (error) => {
-    console.error('Connection error:', error);
+    console.error("Connection error:", error);
   }
 );
 
@@ -226,41 +167,44 @@ eventSource.close();
 ```
 
 ### Raw Datom Queries
+
 Access the raw datom index for high-performance queries:
 
 ```typescript
 // Query EAVT index
-const datoms = await db.datoms('eavt', '-', {
+const datoms = await db.datoms("eavt", "-", {
   e: 12345,
-  limit: 100
+  limit: 100,
 });
 
 // Query AVET index for attribute values
-const attributeValues = await db.datoms('avet', '-', {
-  a: ':person/name',
-  start: 'A',
-  end: 'B'
+const attributeValues = await db.datoms("avet", "-", {
+  a: ":person/name",
+  start: "A",
+  end: "B",
 });
 ```
 
 ### Custom HTTP Configuration
+
 ```typescript
 const client = new DatomicClient({
-  baseUrl: 'https://api.example.com',
+  baseUrl: "https://api.example.com",
   timeout: 30000,
   headers: {
-    'Authorization': 'Bearer token',
-    'X-Custom-Header': 'value'
-  }
+    Authorization: "Bearer token",
+    "X-Custom-Header": "value",
+  },
 });
 ```
 
 ### NextAuth.js Integration
+
 The SDK includes a NextAuth.js adapter for authentication:
 
 ```typescript
-import { AnyDBAdapter } from '@anysoftinc/anydb-sdk/nextauth-adapter';
-import NextAuth from 'next-auth';
+import { AnyDBAdapter } from "@anysoftinc/anydb-sdk/nextauth-adapter";
+import NextAuth from "next-auth";
 
 export default NextAuth({
   adapter: AnyDBAdapter(db),
@@ -278,10 +222,10 @@ The SDK provides detailed error information:
 try {
   const results = await db.query(invalidQuery);
 } catch (error) {
-  if (error.message.includes('Datomic API error')) {
-    console.error('Server error:', error.message);
+  if (error.message.includes("Datomic API error")) {
+    console.error("Server error:", error.message);
   } else {
-    console.error('Client error:', error);
+    console.error("Client error:", error);
   }
 }
 ```
@@ -291,17 +235,17 @@ try {
 Full TypeScript definitions are included:
 
 ```typescript
-import type { 
-  QueryResult, 
-  Transaction, 
-  Entity, 
+import type {
+  QueryResult,
+  Transaction,
+  Entity,
   Datom,
-  DatabaseDescriptor 
-} from '@anysoftinc/anydb-sdk';
+  DatabaseDescriptor,
+} from "@anysoftinc/anydb-sdk";
 
 const processResults = (results: QueryResult): void => {
-  results.forEach(row => {
-    console.log('Row:', row);
+  results.forEach((row) => {
+    console.log("Row:", row);
   });
 };
 ```
@@ -316,21 +260,14 @@ See the [examples directory](./examples/) for complete working examples:
 ## API Reference
 
 ### DatomicClient
-The main client class for interacting with the AnyDB server.
-
-### DatomicDatabase  
-Convenience wrapper for working with a specific database.
 
-### DatomicUtils
-Static utility methods for common Datomic operations.
+The main client class for interacting with the AnyDB server.
 
-### SchemaBuilder
-Helper for building schema definitions.
+### AnyDBClient
 
-### QueryBuilder
-Fluent API for constructing queries programmatically.
+Convenience wrapper for working with a specific database.
 
 ## Related
 
 - [AnyDB Server](../../..) - Backend Clojure implementation
-- [Datomic Documentation](https://docs.datomic.com/) - Official Datomic docs
+- [Datomic Documentation](https://docs.datomic.com/) - Official Datomic docs