{"id":41985797,"url":"https://github.com/junwatu/griddb-client","last_synced_at":"2026-04-01T19:07:27.289Z","repository":{"id":311540819,"uuid":"1044001356","full_name":"junwatu/griddb-client","owner":"junwatu","description":"A modern TypeScript client for GridDB Web API with full CRUD operations, cloud support, and comprehensive testing","archived":false,"fork":false,"pushed_at":"2026-03-24T09:40:23.000Z","size":161,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T17:49:28.679Z","etag":null,"topics":["crud","database-client","griddb","iot","nodejs","nosql","time-series","typescript","web-api"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/junwatu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-25T03:28:20.000Z","updated_at":"2026-03-24T09:39:50.000Z","dependencies_parsed_at":"2025-08-25T06:42:38.830Z","dependency_job_id":"32e9a8fa-ccf9-41dd-9064-ae06e6dd4fe1","html_url":"https://github.com/junwatu/griddb-client","commit_stats":null,"previous_names":["junwatu/griddb-client"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/junwatu/griddb-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junwatu%2Fgriddb-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junwatu%2Fgriddb-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junwatu%2Fgriddb-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junwatu%2Fgriddb-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/junwatu","download_url":"https://codeload.github.com/junwatu/griddb-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junwatu%2Fgriddb-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["crud","database-client","griddb","iot","nodejs","nosql","time-series","typescript","web-api"],"created_at":"2026-01-26T00:12:40.768Z","updated_at":"2026-04-01T19:07:27.276Z","avatar_url":"https://github.com/junwatu.png","language":"TypeScript","readme":"# @junwatu/griddb-client\n\n[![npm version](https://badge.fury.io/js/%40junwatu%2Fgriddb-client.svg)](https://www.npmjs.com/package/@junwatu/griddb-client)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA comprehensive TypeScript/JavaScript client library for GridDB Web API with full CRUD operations support.\n\n## Features\n\n- 🚀 **Full CRUD Operations**: Create, Read, Update, Delete with ease\n- 🔄 **Batch Operations**: Efficient batch inserts with error handling\n- 🛡️ **Type Safety**: Full TypeScript support with comprehensive type definitions\n- 🔌 **Connection Management**: Automatic retry logic and connection pooling\n- 🎯 **SQL \u0026 TQL Support**: Execute both SQL and TQL queries\n- 🔧 **Utility Functions**: ID generation, data transformation, and more\n- 📊 **Container Management**: Create, drop, and manage GridDB containers\n- ⚡ **Performance Optimized**: Batching, connection reuse, and efficient transformations\n\n## Installation\n\n```bash\nnpm install @junwatu/griddb-client\n```\n\nor\n\n```bash\nyarn add @junwatu/griddb-client\n```\n\n## Quick Start\n\n### 1. Set up environment variables\n\nCreate a `.env` file in your project root:\n\n```env\nGRIDDB_WEBAPI_URL=http://localhost:8080/griddb/v2\nGRIDDB_USERNAME=admin\nGRIDDB_PASSWORD=admin\n```\n\n### 2. Basic Usage\n\n```typescript\nimport { GridDB } from '@junwatu/griddb-client';\n\n// Initialize the client\nconst griddb = new GridDB({\n  griddbWebApiUrl: process.env.GRIDDB_WEBAPI_URL!,\n  username: process.env.GRIDDB_USERNAME!,\n  password: process.env.GRIDDB_PASSWORD!\n});\n\n// Create a container\nawait griddb.createContainer({\n  containerName: 'users',\n  columns: [\n    { name: 'id', type: 'INTEGER' },\n    { name: 'name', type: 'STRING' },\n    { name: 'email', type: 'STRING' },\n    { name: 'created_at', type: 'TIMESTAMP' }\n  ]\n});\n\n// Insert data\nawait griddb.insert({\n  containerName: 'users',\n  data: {\n    id: 1,\n    name: 'John Doe',\n    email: 'john@example.com',\n    created_at: new Date()\n  }\n});\n\n// Query data\nconst users = await griddb.select({\n  containerName: 'users',\n  where: 'name = ?',\n  bindings: ['John Doe']\n});\n\nconsole.log(users);\n```\n\n## API Documentation\n\n### API Overview\n\n| Method | Description |\n|--------|-------------|\n| `createContainer(options)` | Create a new container |\n| `dropContainer(name)` | Drop a container |\n| `listContainers()` | List all containers |\n| `containerExists(name)` | Check if container exists |\n| `getSchema(name)` | Get container schema |\n| `insert(options)` | Insert one or more rows |\n| `batchInsert(name, data, batchSize)` | Batch insert with error handling |\n| `select(options)` | Query rows with conditions |\n| `selectOne(options)` | Query a single row |\n| `count(name, where?, bindings?)` | Count rows |\n| `exists(name, where, bindings?)` | Check if rows exist |\n| `update(options)` | Update rows (by rowkey or WHERE clause) |\n| `delete(options)` | Delete rows by condition |\n| `truncate(name)` | Delete all rows from container |\n| `upsert(name, data, uniqueColumns)` | Insert or update |\n| `executeSql(stmt, bindings?)` | Execute raw SELECT query |\n| `executeDml(stmt, bindings?)` | Execute raw DML (INSERT/UPDATE/DELETE) |\n| `executeTql(name, query)` | Execute TQL query |\n\n### Initialization\n\n```typescript\nimport { GridDB, GridDBConfig } from '@junwatu/griddb-client';\n\nconst config: GridDBConfig = {\n  griddbWebApiUrl: 'http://localhost:8080/griddb/v2',\n  username: 'admin',\n  password: 'admin',\n  timeout: 30000,        // Optional: Request timeout in ms (default: 30000)\n  retryAttempts: 3,      // Optional: Number of retry attempts (default: 3)\n  retryDelay: 1000       // Optional: Delay between retries in ms (default: 1000)\n};\n\nconst griddb = new GridDB(config);\n```\n\n### Container Operations\n\n#### Create Container\n\n```typescript\nawait griddb.createContainer({\n  containerName: 'my_container',\n  columns: [\n    { name: 'id', type: 'INTEGER' },\n    { name: 'data', type: 'BLOB' },\n    { name: 'timestamp', type: 'TIMESTAMP' }\n  ],\n  containerType: 'COLLECTION',  // or 'TIME_SERIES'\n  rowkey: true,                  // First column as primary key\n  ifNotExists: true              // Don't error if exists\n});\n```\n\n#### Drop Container\n\n```typescript\nawait griddb.dropContainer('my_container');\n```\n\n#### List Containers\n\n```typescript\nconst containers = await griddb.listContainers();\nconsole.log(containers); // ['users', 'products', ...]\n```\n\n### CRUD Operations\n\n#### Insert\n\n```typescript\n// Object-based insert (property order doesn't matter)\nawait griddb.insert({\n  containerName: 'users',\n  data: { name: 'Alice', email: 'alice@example.com', id: 1 }\n});\n\n// Multiple insert with objects\nawait griddb.insert({\n  containerName: 'users',\n  data: [\n    { name: 'Bob', email: 'bob@example.com', id: 2 },\n    { name: 'Charlie', email: 'charlie@example.com', id: 3 }\n  ]\n});\n\n// Mixed object and array data\nawait griddb.insert({\n  containerName: 'users',\n  data: [\n    { name: 'Dave', email: 'dave@example.com', id: 4 },\n    [5, 'Eve', 'eve@example.com'] // Arrays must follow column order\n  ]\n});\n\n// Batch insert with error handling\nconst result = await griddb.batchInsert('users', largeDataArray, 100);\nconsole.log(`Succeeded: ${result.succeeded}, Failed: ${result.failed}`);\n```\n\n#### Select\n\n```typescript\n// Select all\nconst allUsers = await griddb.select({ containerName: 'users' });\n\n// Select with conditions\nconst activeUsers = await griddb.select({\n  containerName: 'users',\n  columns: ['id', 'name', 'email'],\n  where: 'status = ? AND created_at \u003e ?',\n  bindings: ['active', '2024-01-01'],\n  orderBy: 'created_at',\n  order: 'DESC',\n  limit: 10,\n  offset: 0\n});\n\n// Select one\nconst user = await griddb.selectOne({\n  containerName: 'users',\n  where: 'id = ?',\n  bindings: [1]\n});\n```\n\n#### Update\n\n```typescript\n// Update by primary key (upsert via rowkey — recommended)\nawait griddb.update({\n  containerName: 'users',\n  data: { id: 1, name: 'Alice Updated', email: 'alice.new@example.com' }\n});\n\n// Update with WHERE clause\nawait griddb.update({\n  containerName: 'users',\n  data: { status: 'inactive' },\n  where: `last_login \u003c '2023-01-01'`\n});\n```\n\n\u003e **Note:** When no `where` clause is provided, update uses the Row API (PUT) which upserts by rowkey. When a `where` clause is provided, it uses SQL UPDATE via the DML endpoint. For GridDB Cloud, prefer inline values in the WHERE clause over parameterized `bindings`.\n\n#### Delete\n\n```typescript\n// Delete by ID\nawait griddb.delete({\n  containerName: 'users',\n  where: 'id = 1'\n});\n\n// Delete with condition\nawait griddb.delete({\n  containerName: 'users',\n  where: `status = 'inactive'`\n});\n```\n\n#### Upsert\n\n```typescript\nawait griddb.upsert(\n  'users',\n  { id: 1, name: 'Alice', email: 'alice@example.com' },\n  ['id']  // Unique columns to check\n);\n```\n\n#### Truncate\n\n```typescript\n// Delete all rows from a container\nawait griddb.truncate('users');\n```\n\n### Query Execution\n\n#### SQL Queries (SELECT)\n\nUse `executeSql` for read-only SELECT queries. This sends `type: 'sql-select'` to the `/sql/dml/query` endpoint.\n\n```typescript\nconst result = await griddb.executeSql(\n  'SELECT * FROM users WHERE age \u003e ? ORDER BY name',\n  [18]\n);\nconsole.log(result.results);\n```\n\n#### SQL DML Statements (INSERT, UPDATE, DELETE)\n\nUse `executeDml` for data modification statements. This sends `type: 'sql-update'` to the `/sql/update` endpoint, which is required by GridDB Cloud Web API for DML operations.\n\n```typescript\n// Delete with raw SQL\nconst result = await griddb.executeDml(\n  'DELETE FROM users WHERE status = ?',\n  ['inactive']\n);\nconsole.log(result.updatedRows);\n\n// Update with raw SQL\nawait griddb.executeDml(\n  'UPDATE users SET status = ? WHERE last_login \u003c ?',\n  ['inactive', '2023-01-01']\n);\n```\n\n\u003e **Note:** The high-level `delete()`, `update()`, and `truncate()` methods use `executeDml` internally. You only need `executeDml` directly for complex DML statements not covered by the convenience methods.\n\n#### TQL Queries\n\n```typescript\nconst result = await griddb.executeTql(\n  'users',\n  'select * where age \u003e 18'\n);\n```\n\n### Utility Functions\n\n#### ID Generation\n\n```typescript\nimport { IdGeneratorFactory } from '@junwatu/griddb-client';\n\n// Random integer ID (1-10000)\nconst randomId = IdGeneratorFactory.random();\n\n// UUID v4\nconst uuid = IdGeneratorFactory.uuid();\n\n// Timestamp-based ID\nconst timestampId = IdGeneratorFactory.timestamp();\n\n// Snowflake-like ID\nconst snowflakeId = IdGeneratorFactory.snowflake();\n\n// Short alphanumeric ID\nconst shortId = IdGeneratorFactory.short(8);\n```\n\n#### Data Transformation\n\n```typescript\nimport { blobToBase64, base64ToBlob } from '@junwatu/griddb-client';\n\n// Convert Blob to base64 for storage\nconst base64 = await blobToBase64(imageBlob);\n\n// Convert base64 back to Blob\nconst blob = base64ToBlob(base64String, 'image/jpeg');\n```\n\n## Advanced Usage\n\n### Custom Logger\n\n```typescript\nconst griddb = new GridDB({\n  config: {\n    griddbWebApiUrl: '...',\n    username: '...',\n    password: '...'\n  },\n  logger: {\n    debug: (msg, ...args) =\u003e console.debug(msg, ...args),\n    info: (msg, ...args) =\u003e console.info(msg, ...args),\n    warn: (msg, ...args) =\u003e console.warn(msg, ...args),\n    error: (msg, ...args) =\u003e console.error(msg, ...args)\n  }\n});\n```\n\n### Working with BLOBs\n\n```typescript\n// Store image as BLOB\nconst imageBuffer = await fs.readFile('image.jpg');\nconst base64Image = imageBuffer.toString('base64');\n\nawait griddb.insert({\n  containerName: 'images',\n  data: {\n    id: 1,\n    image_data: base64Image,\n    mime_type: 'image/jpeg'\n  }\n});\n\n// Retrieve and convert back\nconst result = await griddb.selectOne({\n  containerName: 'images',\n  where: 'id = ?',\n  bindings: [1]\n});\n\nif (result) {\n  const imageBlob = base64ToBlob(result.image_data, result.mime_type);\n  // Use imageBlob...\n}\n```\n\n### Error Handling\n\n```typescript\nimport { GridDBError } from '@junwatu/griddb-client';\n\ntry {\n  await griddb.insert({\n    containerName: 'users',\n    data: { id: 1, name: 'Test' }\n  });\n} catch (error) {\n  if (error instanceof GridDBError) {\n    console.error('GridDB Error:', error.message);\n    console.error('Status:', error.status);\n    console.error('Details:', error.details);\n  } else {\n    console.error('Unexpected error:', error);\n  }\n}\n```\n\n## Type Definitions\n\nThe library exports all type definitions for use in your TypeScript projects:\n\n```typescript\nimport {\n  GridDBConfig,\n  GridDBColumn,\n  GridDBRow,\n  GridDBQuery,\n  ContainerType,\n  GridDBColumnType,\n  CreateOptions,\n  InsertOptions,\n  SelectOptions,\n  UpdateOptions,\n  DeleteOptions,\n  QueryResult,\n  BatchOperationResult\n} from '@junwatu/griddb-client';\n```\n\n### GridDBQuery Type\n\n```typescript\ninterface GridDBQuery {\n  type: 'sql-select' | 'sql-update' | 'tql';\n  stmt: string;\n  bindings?: GridDBValue[];\n}\n```\n\n- `sql-select` — Used for SELECT queries via `/sql/dml/query`\n- `sql-update` — Used for DML statements (INSERT, UPDATE, DELETE) via `/sql/update`\n- `tql` — Used for TQL queries\n\n## GridDB Cloud\n\nThis library fully supports [GridDB Cloud](https://cloud.griddb.com). GridDB Cloud's Web API strictly separates SELECT queries from DML (data modification) operations at the endpoint level:\n\n| Operation | API Type | Endpoint |\n|-----------|----------|----------|\n| SELECT, COUNT | `sql-select` | `/sql/dml/query` |\n| INSERT, UPDATE, DELETE | `sql-update` | `/sql/update` |\n\nThe library handles this automatically — `select()`, `selectOne()`, `count()` use the SELECT endpoint, while `delete()`, `update()` (with WHERE clause), and `truncate()` use the DML endpoint.\n\n\u003e **Tip:** Make sure your IP address is added to the GridDB Cloud allowlist, otherwise all requests will return `403 Forbidden`.\n\n### GridDB Cloud Configuration\n\n```typescript\nconst griddb = new GridDB({\n  griddbWebApiUrl: 'https://cloud1.griddb.com/trial1234/griddb/v2/gs_clustertrial1234/dbs/public',\n  username: 'your_username',\n  password: 'your_password'\n});\n```\n\n## Environment Variables\n\nCreate a `.env` file with the following variables:\n\n```env\n# GridDB Web API Configuration\nGRIDDB_WEBAPI_URL=http://localhost:8080/griddb/v2\nGRIDDB_USERNAME=admin\nGRIDDB_PASSWORD=admin\n\n# Optional\nGRIDDB_TIMEOUT=30000\nGRIDDB_RETRY_ATTEMPTS=3\nGRIDDB_RETRY_DELAY=1000\n```\n\n## Development\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Test\n\n```bash\nnpm test\n```\n\n### Lint\n\n```bash\nnpm run lint\n```\n\n### Format\n\n```bash\nnpm run format\n```\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nFor issues and questions, please use the [GitHub Issues](https://github.com/junwatu/griddb-client/issues) page.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunwatu%2Fgriddb-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjunwatu%2Fgriddb-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunwatu%2Fgriddb-client/lists"}