@anysoftinc/anydb-sdk/README.md

AnyDB TypeScript SDK for querying and transacting with Datomic databases

# AnyDB TypeScript SDK

TypeScript SDK for querying and transacting with Datomic databases via the AnyDB server.

## Installation

```bash
npm install @anysoftinc/anydb-sdk
```

## Quick Start

```typescript
import {
  DatomicClient,
  createAnyDBClient,
  kw,
  sym,
  uuid,
} from "@anysoftinc/anydb-sdk";

// Create a client
const client = new DatomicClient({
  baseUrl: "http://localhost:4000",
  getAuthToken: () => process.env.ANYDB_TOKEN!,
});

// Create a database wrapper for convenience
const db = createAnyDBClient(client, "sql", "db-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 (keywordized keys, kw()/uuid() for values)
await db.transact([
  {
    ["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
- **Entity Lookup** - Retrieve individual entities
- **Datom Access** - Raw datom queries with indexing

### Query Types

Traditional array-based queries are not supported in v2.

#### Symbolic Queries (Type-safe)

```typescript
import { sym, kw } from "@anysoftinc/anydb-sdk";

const query = {
  find: [sym("?e"), sym("?name")],
  where: [[sym("?e"), kw("person/name"), sym("?name")]],
};
const results = await db.query(query);
```

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
- **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,
  },
]);

// 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,
  },
]);
```

SchemaBuilder and DatomicUtils have been removed in v2. Use plain tx maps with keywordized keys and kw()/uuid() for values.

### Utility Functions

Utility helpers for tempids and entity builders were removed in v2.

### Idempotent Schema Install

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.

```ts
import { ensureAttributes, kw } from "@anysoftinc/anydb-sdk";

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";

// Symbols for query variables
const entityVar = sym("?e");

// Keywords for attributes
const nameAttr = kw("person/name");

// UUIDs
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);
  },
  (error) => {
    console.error("Connection error:", error);
  }
);

// Close the connection when done
eventSource.close();
```

### Raw Datom Queries

Access the raw datom index for high-performance queries:

```typescript
// Query EAVT index
const datoms = await db.datoms("eavt", "-", {
  e: 12345,
  limit: 100,
});

// Query AVET index for attribute values
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",
  timeout: 30000,
  headers: {
    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";

export default NextAuth({
  adapter: AnyDBAdapter(db),
  providers: [
    // Your providers
  ],
});
```

## Error Handling

The SDK provides detailed error information:

```typescript
try {
  const results = await db.query(invalidQuery);
} catch (error) {
  if (error.message.includes("Datomic API error")) {
    console.error("Server error:", error.message);
  } else {
    console.error("Client error:", error);
  }
}
```

## TypeScript Support

Full TypeScript definitions are included:

```typescript
import type {
  QueryResult,
  Transaction,
  Entity,
  Datom,
  DatabaseDescriptor,
} from "@anysoftinc/anydb-sdk";

const processResults = (results: QueryResult): void => {
  results.forEach((row) => {
    console.log("Row:", row);
  });
};
```

## Examples

See the [examples directory](./examples/) for complete working examples:

- **[Console Example](./examples/console/)** - Web-based query interface with Monaco Editor
- **[NextAuth.js Example](./examples/nextauth-example.md)** - Authentication adapter for NextAuth.js

## API Reference

### DatomicClient

The main client class for interacting with the AnyDB server.

### AnyDBClient

Convenience wrapper for working with a specific database.

## Related

- [AnyDB Server](../../..) - Backend Clojure implementation
- [Datomic Documentation](https://docs.datomic.com/) - Official Datomic docs