@junwatu/griddb-client

A comprehensive TypeScript/JavaScript client library for GridDB Web API with full CRUD operations support.

Features

• 🚀 Full CRUD Operations: Create, Read, Update, Delete with ease
• 🔄 Batch Operations: Efficient batch inserts with error handling
• 🛡️ Type Safety: Full TypeScript support with comprehensive type definitions
• 🔌 Connection Management: Automatic retry logic and connection pooling
• 🎯 SQL & TQL Support: Execute both SQL and TQL queries
• 🔧 Utility Functions: ID generation, data transformation, and more
• 📊 Container Management: Create, drop, and manage GridDB containers
• ⚡ Performance Optimized: Batching, connection reuse, and efficient transformations

Installation

npm install @junwatu/griddb-client

or

yarn add @junwatu/griddb-client

Quick Start

1. Set up environment variables

Create a .env file in your project root:

GRIDDB_WEBAPI_URL=http://localhost:8080/griddb/v2
GRIDDB_USERNAME=admin
GRIDDB_PASSWORD=admin

2. Basic Usage

import { GridDB } from '@junwatu/griddb-client';

// Initialize the client
const griddb = new GridDB({
  griddbWebApiUrl: process.env.GRIDDB_WEBAPI_URL!,
  username: process.env.GRIDDB_USERNAME!,
  password: process.env.GRIDDB_PASSWORD!
});

// Create a container
await griddb.createContainer({
  containerName: 'users',
  columns: [
    { name: 'id', type: 'INTEGER' },
    { name: 'name', type: 'STRING' },
    { name: 'email', type: 'STRING' },
    { name: 'created_at', type: 'TIMESTAMP' }
  ]
});

// Insert data
await griddb.insert({
  containerName: 'users',
  data: {
    id: 1,
    name: 'John Doe',
    email: 'john@example.com',
    created_at: new Date()
  }
});

// Query data
const users = await griddb.select({
  containerName: 'users',
  where: 'name = ?',
  bindings: ['John Doe']
});

console.log(users);

API Documentation

Initialization

import { GridDB, GridDBConfig } from '@junwatu/griddb-client';

const config: GridDBConfig = {
  griddbWebApiUrl: 'http://localhost:8080/griddb/v2',
  username: 'admin',
  password: 'admin',
  timeout: 30000,        // Optional: Request timeout in ms (default: 30000)
  retryAttempts: 3,      // Optional: Number of retry attempts (default: 3)
  retryDelay: 1000       // Optional: Delay between retries in ms (default: 1000)
};

const griddb = new GridDB(config);

Container Operations

Create Container

await griddb.createContainer({
  containerName: 'my_container',
  columns: [
    { name: 'id', type: 'INTEGER' },
    { name: 'data', type: 'BLOB' },
    { name: 'timestamp', type: 'TIMESTAMP' }
  ],
  containerType: 'COLLECTION',  // or 'TIME_SERIES'
  rowkey: true,                  // First column as primary key
  ifNotExists: true              // Don't error if exists
});

Drop Container

await griddb.dropContainer('my_container');

List Containers

const containers = await griddb.listContainers();
console.log(containers); // ['users', 'products', ...]

CRUD Operations

Insert

// Object-based insert (property order doesn't matter)
await griddb.insert({
  containerName: 'users',
  data: { name: 'Alice', email: 'alice@example.com', id: 1 }
});

// Multiple insert with objects
await griddb.insert({
  containerName: 'users',
  data: [
    { name: 'Bob', email: 'bob@example.com', id: 2 },
    { name: 'Charlie', email: 'charlie@example.com', id: 3 }
  ]
});

// Mixed object and array data
await griddb.insert({
  containerName: 'users',
  data: [
    { name: 'Dave', email: 'dave@example.com', id: 4 },
    [5, 'Eve', 'eve@example.com'] // Arrays must follow column order
  ]
});

// Batch insert with error handling
const result = await griddb.batchInsert('users', largeDataArray, 100);
console.log(`Succeeded: ${result.succeeded}, Failed: ${result.failed}`);

Select

// Select all
const allUsers = await griddb.select({ containerName: 'users' });

// Select with conditions
const activeUsers = await griddb.select({
  containerName: 'users',
  columns: ['id', 'name', 'email'],
  where: 'status = ? AND created_at > ?',
  bindings: ['active', '2024-01-01'],
  orderBy: 'created_at',
  order: 'DESC',
  limit: 10,
  offset: 0
});

// Select one
const user = await griddb.selectOne({
  containerName: 'users',
  where: 'id = ?',
  bindings: [1]
});

Update

// Update by primary key
await griddb.update({
  containerName: 'users',
  data: { id: 1, name: 'Alice Updated', email: 'alice.new@example.com' }
});

// Update with conditions
await griddb.update({
  containerName: 'users',
  data: { status: 'inactive' },
  where: 'last_login < ?',
  bindings: ['2023-01-01']
});

Delete

await griddb.delete({
  containerName: 'users',
  where: 'id = ?',
  bindings: [1]
});

Upsert

await griddb.upsert(
  'users',
  { id: 1, name: 'Alice', email: 'alice@example.com' },
  ['id']  // Unique columns to check
);

Query Execution

SQL Queries

const result = await griddb.executeSql(
  'SELECT * FROM users WHERE age > ? ORDER BY name',
  [18]
);
console.log(result.results);

TQL Queries

const result = await griddb.executeTql(
  'users',
  'select * where age > 18'
);

Utility Functions

ID Generation

import { IdGeneratorFactory } from '@junwatu/griddb-client';

// Random integer ID (1-10000)
const randomId = IdGeneratorFactory.random();

// UUID v4
const uuid = IdGeneratorFactory.uuid();

// Timestamp-based ID
const timestampId = IdGeneratorFactory.timestamp();

// Snowflake-like ID
const snowflakeId = IdGeneratorFactory.snowflake();

// Short alphanumeric ID
const shortId = IdGeneratorFactory.short(8);

Data Transformation

import { blobToBase64, base64ToBlob } from '@junwatu/griddb-client';

// Convert Blob to base64 for storage
const base64 = await blobToBase64(imageBlob);

// Convert base64 back to Blob
const blob = base64ToBlob(base64String, 'image/jpeg');

Advanced Usage

Custom Logger

const griddb = new GridDB({
  config: {
    griddbWebApiUrl: '...',
    username: '...',
    password: '...'
  },
  logger: {
    debug: (msg, ...args) => console.debug(msg, ...args),
    info: (msg, ...args) => console.info(msg, ...args),
    warn: (msg, ...args) => console.warn(msg, ...args),
    error: (msg, ...args) => console.error(msg, ...args)
  }
});

Working with BLOBs

// Store image as BLOB
const imageBuffer = await fs.readFile('image.jpg');
const base64Image = imageBuffer.toString('base64');

await griddb.insert({
  containerName: 'images',
  data: {
    id: 1,
    image_data: base64Image,
    mime_type: 'image/jpeg'
  }
});

// Retrieve and convert back
const result = await griddb.selectOne({
  containerName: 'images',
  where: 'id = ?',
  bindings: [1]
});

if (result) {
  const imageBlob = base64ToBlob(result.image_data, result.mime_type);
  // Use imageBlob...
}

Error Handling

import { GridDBError } from '@junwatu/griddb-client';

try {
  await griddb.insert({
    containerName: 'users',
    data: { id: 1, name: 'Test' }
  });
} catch (error) {
  if (error instanceof GridDBError) {
    console.error('GridDB Error:', error.message);
    console.error('Status:', error.status);
    console.error('Details:', error.details);
  } else {
    console.error('Unexpected error:', error);
  }
}

Type Definitions

The library exports all type definitions for use in your TypeScript projects:

import {
  GridDBConfig,
  GridDBColumn,
  GridDBRow,
  ContainerType,
  GridDBColumnType,
  CreateOptions,
  InsertOptions,
  SelectOptions,
  UpdateOptions,
  DeleteOptions,
  QueryResult,
  BatchOperationResult
} from '@junwatu/griddb-client';

Environment Variables

Create a .env file with the following variables:

# GridDB Web API Configuration
GRIDDB_WEBAPI_URL=http://localhost:8080/griddb/v2
GRIDDB_USERNAME=admin
GRIDDB_PASSWORD=admin

# Optional
GRIDDB_TIMEOUT=30000
GRIDDB_RETRY_ATTEMPTS=3
GRIDDB_RETRY_DELAY=1000

Development

Build

npm run build

Test

npm test

Lint

npm run lint

Format

npm run format

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub Issues page.