API Reference

API Reference

This comprehensive reference covers all methods available in the OstrichDB JavaScript/TypeScript SDK. The SDK provides both traditional method-based APIs and an intuitive builder pattern for all database operations.

Client Initialization

Constructor

new OstrichDB(config: OstrichDBConfig)

Parameters:

• config - Configuration object for the client

Example:

import OstrichDB from 'ostrichdb-js';

const db = new OstrichDB({
  baseUrl: 'http://localhost:8042',
  apiKey: 'your-jwt-token',
  timeout: 30000
});

Client Methods

setAuthToken(token: string): void

Updates the authentication token for the client.

Parameters:

• token - New JWT authentication token

Example:

db.setAuthToken('new-jwt-token-here');

Project Operations

list_projects(): Promise<Project[]>

Retrieves all projects for the authenticated user.

Returns: Array of project objects

Example:

const projects = await db.list_projects();
console.log('Projects:', projects);

create_project(name: string): Promise<void>

Creates a new project with the specified name.

Parameters:

• name - Project name (must follow naming conventions)

Example:

await db.create_project('my-application');

delete_project(name: string): Promise<void>

Permanently deletes a project and all its contents.

Parameters:

• name - Project name to delete

Example:

await db.delete_project('old-project');

Collection Operations

list_collections(project: string): Promise<Collection[]>

Lists all collections within a project.

Parameters:

• project - Project name

Returns: Array of collection objects

Example:

const collections = await db.list_collections('my-application');

create_collection(project: string, collection: string): Promise<void>

Creates a new collection within a project.

Parameters:

• project - Project name
• collection - Collection name

Example:

await db.create_collection('my-application', 'user-data');

get_collection(project: string, collection: string): Promise<CollectionData>

Retrieves detailed information about a collection.

Parameters:

• project - Project name
• collection - Collection name

Returns: Collection data with metadata

Example:

const collectionInfo = await db.get_collection('my-application', 'user-data');

delete_collection(project: string, collection: string): Promise<void>

Permanently deletes a collection and all its contents.

Parameters:

• project - Project name
• collection - Collection name

Example:

await db.delete_collection('my-application', 'old-collection');

Cluster Operations

list_clusters(project: string, collection: string): Promise<Cluster[]>

Lists all clusters within a collection.

Parameters:

• project - Project name
• collection - Collection name

Returns: Array of cluster objects

Example:

const clusters = await db.list_clusters('my-application', 'user-data');

create_cluster(project: string, collection: string, cluster: string): Promise<void>

Creates a new cluster within a collection.

Parameters:

• project - Project name
• collection - Collection name
• cluster - Cluster name

Example:

await db.create_cluster('my-application', 'user-data', 'active-users');

get_cluster(project: string, collection: string, cluster: string): Promise<ClusterData>

Retrieves detailed information about a cluster.

Parameters:

• project - Project name
• collection - Collection name
• cluster - Cluster name

Returns: Cluster data with metadata

Example:

const clusterInfo = await db.get_cluster('my-application', 'user-data', 'active-users');

delete_cluster(project: string, collection: string, cluster: string): Promise<void>

Permanently deletes a cluster and all its records.

Parameters:

• project - Project name
• collection - Collection name
• cluster - Cluster name

Example:

await db.delete_cluster('my-application', 'user-data', 'inactive-users');

Record Operations

create_record(project: string, collection: string, cluster: string, name: string, type: DataType, value: string): Promise<void>

Creates a new record with the specified type and value.

Parameters:

• project - Project name
• collection - Collection name
• cluster - Cluster name
• name - Record name (unique within cluster)
• type - Data type (see Data Types)
• value - Record value as string

Example:

await db.create_record(
  'my-application',
  'user-data',
  'active-users',
  'user-123-name',
  'STRING',
  'John Doe'
);

get_record(project: string, collection: string, cluster: string, identifier: string): Promise<Record>

Retrieves a specific record by name or ID.

Parameters:

• project - Project name
• collection - Collection name
• cluster - Cluster name
• identifier - Record name or ID

Returns: Record object with metadata

Example:

const record = await db.get_record(
  'my-application',
  'user-data',
  'active-users',
  'user-123-name'
);
console.log('Record value:', record.value);

list_records(project: string, collection: string, cluster: string): Promise<Record[]>

Lists all records within a cluster.

Parameters:

• project - Project name
• collection - Collection name
• cluster - Cluster name

Returns: Array of record objects

Example:

const records = await db.list_records('my-application', 'user-data', 'active-users');

delete_record(project: string, collection: string, cluster: string, name: string): Promise<void>

Permanently deletes a record.

Parameters:

• project - Project name
• collection - Collection name
• cluster - Cluster name
• name - Record name

Example:

await db.delete_record('my-application', 'user-data', 'active-users', 'user-123-name');

Search Operations

search_records(project: string, collection: string, cluster: string, options: SearchOptions): Promise<Record[]>

Searches for records with filtering, sorting, and pagination options.

Parameters:

• project - Project name
• collection - Collection name
• cluster - Cluster name
• options - Search and filter options

Search Options:

interface SearchOptions {
  type?: DataType;           // Filter by data type
  search?: string;           // Search in record names
  valueContains?: string;    // Search in record values
  limit?: number;            // Maximum results (default: 100)
  offset?: number;           // Skip first N results (default: 0)
  sortBy?: 'name' | 'value' | 'type' | 'id';  // Sort field
  sortOrder?: 'asc' | 'desc';  // Sort direction
  minValue?: string;         // Minimum value (for numeric types)
  maxValue?: string;         // Maximum value (for numeric types)
}

Examples:

Basic search:

const stringRecords = await db.search_records('app', 'users', 'active', {
  type: 'STRING'
});

Text search:

const nameRecords = await db.search_records('app', 'users', 'active', {
  search: 'name',
  limit: 50
});

Value filtering:

const recentUsers = await db.search_records('app', 'users', 'active', {
  type: 'DATE',
  minValue: '2024-01-01',
  sortBy: 'value',
  sortOrder: 'desc'
});

Pagination:

const page2Records = await db.search_records('app', 'users', 'active', {
  limit: 20,
  offset: 20,
  sortBy: 'name'
});

Complex search:

const expensiveProducts = await db.search_records('ecommerce', 'products', 'electronics', {
  type: 'FLOAT',
  minValue: '500.00',
  maxValue: '2000.00',
  sortBy: 'value',
  sortOrder: 'desc',
  limit: 10
});

Utility Operations

health_check(): Promise<HealthStatus>

Checks the health and connectivity of the OstrichDB server.

Returns: Health status object

Example:

try {
  const health = await db.health_check();
  console.log('Server is healthy:', health);
} catch (error) {
  console.error('Server health check failed:', error);
}

Data Types

Supported Data Types

The following data types are supported for records:

Primitive Types

• CHAR - Single character
• STRING - Text data of any length
• INTEGER - Whole numbers (-2^63 to 2^63-1)
• FLOAT - 64-bit floating-point numbers
• BOOLEAN - true or false values
• NULL - Represents no value

Date and Time Types

• DATE - Calendar dates in YYYY-MM-DD format
• TIME - Time of day in HH:MM:SS format
• DATETIME - Combined date and time in ISO 8601 format

Special Types

• UUID - Universally unique identifiers

Array Types

All primitive types can be arrays by prefixing with []:

• []CHAR - Array of characters
• []STRING - Array of strings
• []INTEGER - Array of integers
• []FLOAT - Array of floats
• []BOOLEAN - Array of booleans
• []DATE - Array of dates
• []TIME - Array of times
• []DATETIME - Array of date-times
• []UUID - Array of UUIDs

Type Validation Examples

// Primitive types
await db.create_record('app', 'data', 'test', 'text', 'STRING', 'Hello World');
await db.create_record('app', 'data', 'test', 'number', 'INTEGER', '42');
await db.create_record('app', 'data', 'test', 'decimal', 'FLOAT', '3.14159');
await db.create_record('app', 'data', 'test', 'flag', 'BOOLEAN', 'true');

// Date and time types
await db.create_record('app', 'data', 'test', 'birthday', 'DATE', '1990-05-15');
await db.create_record('app', 'data', 'test', 'meeting', 'TIME', '14:30:00');
await db.create_record('app', 'data', 'test', 'created', 'DATETIME', '2024-01-15T10:30:00Z');

// Arrays
await db.create_record('app', 'data', 'test', 'tags', '[]STRING', '["admin", "user", "premium"]');
await db.create_record('app', 'data', 'test', 'scores', '[]INTEGER', '[85, 92, 78, 96]');
await db.create_record('app', 'data', 'test', 'prices', '[]FLOAT', '[19.99, 24.50, 12.75]');

Response Objects

Project Object

interface Project {
  name: string;
  created: string;        // ISO 8601 timestamp
  modified: string;       // ISO 8601 timestamp
  collections: number;    // Number of collections
  size: number;          // Size in bytes
}

Collection Object

interface Collection {
  name: string;
  created: string;
  modified: string;
  clusters: number;       // Number of clusters
  records: number;        // Total number of records
  size: number;          // Size in bytes
  encrypted: boolean;     // Whether collection is encrypted
}

Cluster Object

interface Cluster {
  name: string;
  created: string;
  modified: string;
  records: number;        // Number of records
  size: number;          // Size in bytes
}

Record Object

interface Record {
  id: string;            // Internal record ID
  name: string;          // Record name
  type: DataType;        // Data type
  value: any;            // Record value (typed according to type)
  created: string;       // ISO 8601 timestamp
  modified: string;      // ISO 8601 timestamp
  size: number;          // Size in bytes
}

Health Status Object

interface HealthStatus {
  status: 'healthy' | 'unhealthy';
  timestamp: string;     // ISO 8601 timestamp
  version: string;       // Server version
  uptime: number;        // Uptime in seconds
}

Error Handling

OstrichDBError

All SDK methods throw OstrichDBError instances for API-related errors:

interface OstrichDBError extends Error {
  statusCode: number;    // HTTP status code
  response: any;         // Full response object
  message: string;       // Error message
}

Common Error Codes

• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid or missing token)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found (resource doesn’t exist)
• 409 - Conflict (resource already exists)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error (server error)

Error Handling Example

import { OstrichDBError } from 'ostrichdb-js';

try {
  await db.create_project('my-project');
} catch (error) {
  if (error instanceof OstrichDBError) {
    console.error('API Error:');
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);

    if (error.statusCode === 409) {
      console.log('Project already exists');
    } else if (error.statusCode === 401) {
      console.log('Authentication required');
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

Performance Considerations

Batch Operations

For multiple operations, consider grouping them:

// Less efficient - multiple API calls
await db.create_record('app', 'users', 'active', 'user1-name', 'STRING', 'Alice');
await db.create_record('app', 'users', 'active', 'user1-email', 'STRING', 'alice@example.com');
await db.create_record('app', 'users', 'active', 'user1-age', 'INTEGER', '28');

// More efficient - use builder pattern for related operations
const users = db.project('app').collection('users').cluster('active');
await users.record('user1-name', 'STRING', 'Alice').create('user1-name', 'STRING', 'Alice');
await users.record('user1-email', 'STRING', 'alice@example.com').create('user1-email', 'STRING', 'alice@example.com');
await users.record('user1-age', 'INTEGER', '28').create('user1-age', 'INTEGER', '28');

Search Optimization

Use specific filters to reduce data transfer:

// Less efficient - returns all records
const allRecords = await db.list_records('app', 'products', 'electronics');
const expensiveItems = allRecords.filter(record =>
  record.type === 'FLOAT' && parseFloat(record.value) > 1000
);

// More efficient - filter on server
const expensiveItems = await db.search_records('app', 'products', 'electronics', {
  type: 'FLOAT',
  minValue: '1000.00',
  sortBy: 'value',
  sortOrder: 'desc'
});

Connection Reuse

Reuse client instances across your application:

// Good - single instance
const db = new OstrichDB({ /* config */ });

// Use db throughout your application

// Bad - multiple instances
function operation1() {
  const db1 = new OstrichDB({ /* config */ });
  return db1.list_projects();
}

function operation2() {
  const db2 = new OstrichDB({ /* config */ }); // Unnecessary new instance
  return db2.list_collections('project');
}

TypeScript Support

The SDK includes full TypeScript definitions:

import OstrichDB, {
  OstrichDBConfig,
  Project,
  Collection,
  Cluster,
  Record,
  SearchOptions,
  DataType,
  OstrichDBError
} from 'ostrichdb-js';

// Type-safe configuration
const config: OstrichDBConfig = {
  baseUrl: 'http://localhost:8042',
  apiKey: 'token',
  timeout: 30000
};

const db = new OstrichDB(config);

// Type-safe operations
const projects: Project[] = await db.list_projects();
const records: Record[] = await db.search_records('app', 'users', 'active', {
  type: 'STRING',
  limit: 50
});

Next Steps

Now that you understand the complete API:

1. Learn the Builder Pattern - Use the intuitive, chainable API
2. Framework Integration - See examples with popular frameworks
3. Error Handling - Implement comprehensive error management
4. Configuration - Optimize client configuration for your environment

The API reference provides the foundation for all SDK operations. Combine these methods with the builder pattern for the most intuitive development experience.