@takyonic/sdk 1.0.0

package/README.md

@@ -0,0 +1,295 @@
+# @takyonic/sdk
+
+Official Node.js SDK for Takyonic - A high-performance caching engine.
+
+## Features
+
+- **Fluent/Chainable API** - Intuitive query building with method chaining
+- **Type Safety** - Full TypeScript support with generics
+- **Automatic URL Encoding** - Query parameters are automatically encoded
+- **Bulk Write Batching** - Large datasets are automatically chunked into optimal batches
+- **Zero Dependencies** - Uses native `fetch` (Node.js 18+)
+- **Comprehensive Error Handling** - Typed error classes for different failure scenarios
+
+## Installation
+
+```bash
+npm install @takyonic/sdk
+```
+
+## Requirements
+
+- Node.js 18.0.0 or higher (for native `fetch` support)
+
+## Quick Start
+
+```typescript
+import { TakyonicClient } from '@takyonic/sdk';
+
+// Initialize the client
+const db = new TakyonicClient({
+  endpoint: 'http://localhost:8080',
+  token: 'your-api-token'
+});
+
+// Query with filters
+const logs = await db.table('logs')
+  .where('severity', '>', 4)
+  .get();
+
+// Find a single record
+const user = await db.table('users').findById('user-123');
+
+// Insert a record
+await db.table('users').insert({
+  id: 'user-456',
+  name: 'Jane Doe',
+  email: 'jane@example.com'
+});
+```
+
+## API Reference
+
+### TakyonicClient
+
+The main entry point for interacting with the Takyonic engine.
+
+#### Constructor
+
+```typescript
+const db = new TakyonicClient({
+  endpoint: 'http://localhost:8080',  // Required: Takyonic server URL
+  token: 'your-api-token',             // Required: Bearer token for auth
+  timeout: 30000                        // Optional: Request timeout in ms (default: 30000)
+});
+```
+
+#### Methods
+
+##### `table<T>(name: string): TableBuilder<T>`
+
+Creates a TableBuilder for the specified table.
+
+```typescript
+const builder = db.table('logs');
+const typedBuilder = db.table<LogRecord>('logs');
+```
+
+##### `stats(): Promise<ServerStats>`
+
+Fetches server statistics.
+
+```typescript
+const stats = await db.stats();
+console.log(`Cache hits: ${stats.cache_hits}`);
+console.log(`Cache misses: ${stats.cache_misses}`);
+console.log(`Total requests: ${stats.total_requests}`);
+```
+
+##### `schema(): Promise<SchemaResponse>`
+
+Fetches the database schema.
+
+```typescript
+const schema = await db.schema();
+for (const table of schema.tables) {
+  console.log(`Table: ${table.name}`);
+  for (const col of table.columns) {
+    console.log(`  - ${col.name}: ${col.data_type}`);
+  }
+}
+```
+
+### TableBuilder
+
+Provides a fluent API for querying and modifying table data.
+
+#### Query Methods
+
+##### `where(column, operator, value): TableBuilder`
+
+Adds a filter condition. Multiple `where()` calls are combined with AND.
+
+```typescript
+const results = await db.table('logs')
+  .where('severity', '>=', 3)
+  .where('event', '=', 'login')
+  .get();
+```
+
+**Supported operators:** `>`, `<`, `>=`, `<=`, `=`, `!=`
+
+##### `search(column: string, query: string): TableBuilder`
+
+Adds a full-text search filter using PostgreSQL FTS with GIN indexes.
+
+```typescript
+// Find logs containing "critical" in the event field
+const logs = await db.table('logs')
+  .search('event', 'critical')
+  .get();
+
+// Multi-word search (words are combined with AND)
+const errors = await db.table('logs')
+  .search('event', 'database connection')
+  .get();
+
+// Combine FTS with regular filters
+const criticalErrors = await db.table('logs')
+  .search('event', 'critical')
+  .where('severity', '>=', 4)
+  .get();
+```
+
+##### `get(): Promise<T[]>`
+
+Executes the query and returns matching records.
+
+```typescript
+const logs = await db.table('logs')
+  .where('severity', '>', 4)
+  .get();
+```
+
+##### `findById(id: string): Promise<T | null>`
+
+Fetches a single record by ID. Returns `null` if not found.
+
+```typescript
+const user = await db.table('users').findById('user-123');
+if (user) {
+  console.log(user.name);
+}
+```
+
+#### Write Methods
+
+##### `insert(data: T): Promise<WriteResult>`
+
+Inserts a new record or updates an existing one (upsert).
+
+```typescript
+await db.table('users').insert({
+  id: 'user-123',
+  name: 'John Doe',
+  email: 'john@example.com'
+});
+```
+
+##### `upsert(data: T): Promise<WriteResult>`
+
+Alias for `insert()`.
+
+##### `insertMany(records: T[]): Promise<BulkInsertResult>`
+
+Inserts multiple records with automatic batching. Large arrays are automatically chunked into batches of 1000 records.
+
+```typescript
+const logs = Array.from({ length: 5000 }, (_, i) => ({
+  id: `log-${i}`,
+  message: `Log entry ${i}`,
+  severity: Math.floor(Math.random() * 5)
+}));
+
+const result = await db.table('logs').insertMany(logs);
+console.log(`Inserted ${result.totalInserted} records`);
+console.log(`Processed ${result.batchesProcessed} batches`);
+```
+
+#### Cache Methods
+
+##### `invalidateCache(id: string): Promise<void>`
+
+Invalidates the cache for a specific record.
+
+```typescript
+await db.table('users').invalidateCache('user-123');
+```
+
+## Error Handling
+
+The SDK provides typed error classes for different failure scenarios:
+
+```typescript
+import {
+  TakyonicError,
+  AuthenticationError,
+  NotFoundError,
+  ValidationError,
+  ServerError,
+  NetworkError
+} from '@takyonic/sdk';
+
+try {
+  await db.table('users').findById('user-123');
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API token');
+  } else if (error instanceof NotFoundError) {
+    console.error('Record not found');
+  } else if (error instanceof ValidationError) {
+    console.error('Invalid request:', error.message);
+  } else if (error instanceof NetworkError) {
+    console.error('Network error:', error.message);
+  } else if (error instanceof TakyonicError) {
+    console.error(`Error ${error.statusCode}: ${error.message}`);
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions.
+
+### Generic Types
+
+Use generics to type your table records:
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  age: number;
+}
+
+// Typed queries
+const users = await db.table<User>('users')
+  .where('age', '>=', 18)
+  .get();
+
+// users is typed as User[]
+
+const user = await db.table<User>('users').findById('user-123');
+// user is typed as User | null
+
+// Typed inserts
+await db.table<User>('users').insert({
+  id: 'user-456',
+  name: 'Jane',
+  email: 'jane@example.com',
+  age: 25
+});
+```
+
+### Available Types
+
+```typescript
+import type {
+  TakyonicConfig,
+  ComparisonOperator,
+  Filter,
+  BaseRecord,
+  WriteResult,
+  BulkInsertResult,
+  ServerStats,
+  SchemaResponse,
+  TableSchema,
+  ColumnSchema
+} from '@takyonic/sdk';
+```
+
+## License
+
+MIT
+

package/dist/admin-client.d.ts

@@ -0,0 +1,64 @@
+import type { AdminConfig, TableSchema, MigrationResult } from './types';
+/**
+ * Admin Client - For privileged administrative operations on the Takyonic engine.
+ *
+ * This client uses the admin secret (not the regular API key) and provides
+ * access to admin-only endpoints like schema migrations.
+ *
+ * @example
+ * ```typescript
+ * const admin = new AdminClient({
+ *   endpoint: 'http://localhost:8080',
+ *   adminSecret: 'your-admin-secret'
+ * });
+ *
+ * // Run a migration
+ * const result = await admin.migrate([
+ *   { name: 'users', columns: [...] }
+ * ]);
+ *
+ * console.log(`Created tables: ${result.tables_created.join(', ')}`);
+ * ```
+ */
+export declare class AdminClient {
+    private readonly endpoint;
+    private readonly adminSecret;
+    private readonly timeout;
+    constructor(config: AdminConfig);
+    /**
+     * Executes a schema migration on the Takyonic server.
+     *
+     * This is a non-destructive operation that:
+     * - Creates new tables if they don't exist
+     * - Adds new columns to existing tables
+     * - Does NOT delete tables or columns
+     *
+     * @param schema - Array of table schemas to migrate
+     * @returns Promise resolving to the migration result
+     *
+     * @example
+     * ```typescript
+     * const result = await admin.migrate([
+     *   {
+     *     name: 'logs',
+     *     columns: [
+     *       { name: 'id', data_type: 'text', nullable: false },
+     *       { name: 'message', data_type: 'text', nullable: true },
+     *       { name: 'severity', data_type: 'integer', nullable: false }
+     *     ]
+     *   }
+     * ]);
+     *
+     * if (result.tables_created.length > 0) {
+     *   console.log('Created tables:', result.tables_created);
+     * }
+     * ```
+     */
+    migrate(schema: TableSchema[]): Promise<MigrationResult>;
+    /**
+     * Gets the configured endpoint URL.
+     * @internal
+     */
+    getEndpoint(): string;
+}
+//# sourceMappingURL=admin-client.d.ts.map

package/dist/admin-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-client.d.ts","sourceRoot":"","sources":["../src/admin-client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,eAAe,EAEhB,MAAM,SAAS,CAAC;AAOjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,WAAW;IAO/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAwD9D;;;OAGG;IACH,WAAW,IAAI,MAAM;CAGtB"}

package/dist/admin-client.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdminClient = void 0;
+const errors_1 = require("./errors");
+/**
+ * Default configuration values
+ */
+const DEFAULT_TIMEOUT = 30000;
+/**
+ * Admin Client - For privileged administrative operations on the Takyonic engine.
+ *
+ * This client uses the admin secret (not the regular API key) and provides
+ * access to admin-only endpoints like schema migrations.
+ *
+ * @example
+ * ```typescript
+ * const admin = new AdminClient({
+ *   endpoint: 'http://localhost:8080',
+ *   adminSecret: 'your-admin-secret'
+ * });
+ *
+ * // Run a migration
+ * const result = await admin.migrate([
+ *   { name: 'users', columns: [...] }
+ * ]);
+ *
+ * console.log(`Created tables: ${result.tables_created.join(', ')}`);
+ * ```
+ */
+class AdminClient {
+    endpoint;
+    adminSecret;
+    timeout;
+    constructor(config) {
+        // Remove trailing slash from endpoint
+        this.endpoint = config.endpoint.replace(/\/+$/, '');
+        this.adminSecret = config.adminSecret;
+        this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    }
+    /**
+     * Executes a schema migration on the Takyonic server.
+     *
+     * This is a non-destructive operation that:
+     * - Creates new tables if they don't exist
+     * - Adds new columns to existing tables
+     * - Does NOT delete tables or columns
+     *
+     * @param schema - Array of table schemas to migrate
+     * @returns Promise resolving to the migration result
+     *
+     * @example
+     * ```typescript
+     * const result = await admin.migrate([
+     *   {
+     *     name: 'logs',
+     *     columns: [
+     *       { name: 'id', data_type: 'text', nullable: false },
+     *       { name: 'message', data_type: 'text', nullable: true },
+     *       { name: 'severity', data_type: 'integer', nullable: false }
+     *     ]
+     *   }
+     * ]);
+     *
+     * if (result.tables_created.length > 0) {
+     *   console.log('Created tables:', result.tables_created);
+     * }
+     * ```
+     */
+    async migrate(schema) {
+        const url = `${this.endpoint}/v1/admin/migrate`;
+        const fetchOptions = {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.adminSecret}`,
+            },
+            body: JSON.stringify(schema),
+        };
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        fetchOptions.signal = controller.signal;
+        try {
+            const response = await fetch(url, fetchOptions);
+            clearTimeout(timeoutId);
+            // Handle non-OK responses
+            if (!response.ok) {
+                let errorResponse;
+                try {
+                    errorResponse = await response.json();
+                }
+                catch {
+                    // Response body might not be valid JSON
+                }
+                throw (0, errors_1.createErrorFromStatus)(response.status, errorResponse);
+            }
+            return await response.json();
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            // Re-throw TakyonicError instances
+            if (error instanceof Error && error.name.includes('Error') && 'statusCode' in error) {
+                throw error;
+            }
+            // Handle abort (timeout)
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new errors_1.NetworkError(`Request timed out after ${this.timeout}ms`);
+            }
+            // Handle network errors
+            if (error instanceof TypeError) {
+                throw new errors_1.NetworkError(`Network request failed: ${error.message}`);
+            }
+            // Re-throw unknown errors
+            throw error;
+        }
+    }
+    /**
+     * Gets the configured endpoint URL.
+     * @internal
+     */
+    getEndpoint() {
+        return this.endpoint;
+    }
+}
+exports.AdminClient = AdminClient;
+//# sourceMappingURL=admin-client.js.map

package/dist/admin-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-client.js","sourceRoot":"","sources":["../src/admin-client.ts"],"names":[],"mappings":";;;AAAA,qCAA+D;AAQ/D;;GAEG;AACH,MAAM,eAAe,GAAG,KAAK,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAa,WAAW;IACL,QAAQ,CAAS;IACjB,WAAW,CAAS;IACpB,OAAO,CAAS;IAEjC,YAAY,MAAmB;QAC7B,sCAAsC;QACtC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,eAAe,CAAC;IACnD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,CAAC,OAAO,CAAC,MAAqB;QACjC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,mBAAmB,CAAC;QAEhD,MAAM,YAAY,GAAgB;YAChC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,eAAe,EAAE,UAAU,IAAI,CAAC,WAAW,EAAE;aAC9C;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC7B,CAAC;QAEF,sCAAsC;QACtC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;QACrE,YAAY,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;QAExC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;YAChD,YAAY,CAAC,SAAS,CAAC,CAAC;YAExB,0BAA0B;YAC1B,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,IAAI,aAAwC,CAAC;gBAC7C,IAAI,CAAC;oBACH,aAAa,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAmB,CAAC;gBACzD,CAAC;gBAAC,MAAM,CAAC;oBACP,wCAAwC;gBAC1C,CAAC;gBACD,MAAM,IAAA,8BAAqB,EAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;YAC9D,CAAC;YAED,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAqB,CAAC;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,YAAY,CAAC,SAAS,CAAC,CAAC;YAExB,mCAAmC;YACnC,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,YAAY,IAAI,KAAK,EAAE,CAAC;gBACpF,MAAM,KAAK,CAAC;YACd,CAAC;YAED,yBAAyB;YACzB,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBAC1D,MAAM,IAAI,qBAAY,CAAC,2BAA2B,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;YACtE,CAAC;YAED,wBAAwB;YACxB,IAAI,KAAK,YAAY,SAAS,EAAE,CAAC;gBAC/B,MAAM,IAAI,qBAAY,CAAC,2BAA2B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YACrE,CAAC;YAED,0BAA0B;YAC1B,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF;AAxGD,kCAwGC"}

package/dist/client.d.ts

@@ -0,0 +1,102 @@
+import { TableBuilder } from './table-builder';
+import type { TakyonicConfig, RequestOptions, ServerStats, SchemaResponse } from './types';
+/**
+ * Takyonic Client - The main entry point for interacting with the Takyonic engine.
+ *
+ * @example
+ * ```typescript
+ * const db = new TakyonicClient({
+ *   endpoint: 'http://localhost:8080',
+ *   token: 'your-api-token'
+ * });
+ *
+ * // Query a table
+ * const logs = await db.table('logs').where('severity', '>', 4).get();
+ *
+ * // Insert a record
+ * await db.table('users').insert({ id: 'user-1', name: 'John' });
+ * ```
+ */
+export declare class TakyonicClient {
+    private readonly endpoint;
+    private readonly token;
+    private readonly timeout;
+    constructor(config: TakyonicConfig);
+    /**
+     * Creates a TableBuilder for the specified table.
+     * This is the starting point for all table operations.
+     *
+     * @param name - The name of the table to query
+     * @returns A TableBuilder instance for fluent query building
+     *
+     * @example
+     * ```typescript
+     * const results = await db.table('logs')
+     *   .where('severity', '>=', 3)
+     *   .get();
+     * ```
+     */
+    table<T extends {
+        id: string;
+    } = {
+        id: string;
+        [key: string]: unknown;
+    }>(name: string): TableBuilder<T>;
+    /**
+     * Fetches server statistics including cache hits, misses, and performance metrics.
+     *
+     * @returns Promise resolving to server statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = await db.stats();
+     * console.log(`Cache hit rate: ${stats.cache_hits / stats.total_requests * 100}%`);
+     * ```
+     */
+    stats(): Promise<ServerStats>;
+    /**
+     * Fetches the database schema including all tables, columns, and relationships.
+     *
+     * @returns Promise resolving to the schema information
+     *
+     * @example
+     * ```typescript
+     * const schema = await db.schema();
+     * for (const table of schema.tables) {
+     *   console.log(`Table: ${table.name}, Columns: ${table.columns.length}`);
+     * }
+     * ```
+     */
+    schema(): Promise<SchemaResponse>;
+    /**
+     * Fetches the database schema as a formatted .takyonic DSL string.
+     * This is the authoritative format from the Rust backend.
+     *
+     * @returns Promise resolving to the DSL string content
+     *
+     * @example
+     * ```typescript
+     * const dsl = await db.schemaDsl();
+     * fs.writeFileSync('.takyonic', dsl);
+     * ```
+     */
+    schemaDsl(): Promise<string>;
+    /**
+     * Internal method to make HTTP requests to the Takyonic server.
+     * Handles authentication, error handling, and response parsing.
+     *
+     * @internal
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    /**
+     * Gets the configured endpoint URL.
+     * @internal
+     */
+    getEndpoint(): string;
+    /**
+     * Gets the configured timeout.
+     * @internal
+     */
+    getTimeout(): number;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,cAAc,EAGf,MAAM,SAAS,CAAC;AAOjB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,cAAc;IAOlC;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,CAAC,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC;IAIvG;;;;;;;;;;OAUG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IAOnC;;;;;;;;;;;;OAYG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAQvC;;;;;;;;;;;OAWG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IA8ClC;;;;;OAKG;IACG,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;IA4ErD;;;OAGG;IACH,WAAW,IAAI,MAAM;IAIrB;;;OAGG;IACH,UAAU,IAAI,MAAM;CAGrB"}