{"id":15041228,"url":"https://github.com/wpdas/chain-db-ts","last_synced_at":"2026-01-26T05:06:36.045Z","repository":{"id":183117994,"uuid":"669389734","full_name":"wpdas/chain-db-ts","owner":"wpdas","description":"A JavaScript / TypeScript (node) client for Chain DB, a secure database system with built-in history tracking, offering AES-256-GCM encryption, atomic operations with rollback capability, and automatic backups.","archived":false,"fork":false,"pushed_at":"2025-03-11T21:08:28.000Z","size":63,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-11T08:21:27.503Z","etag":null,"topics":["chaindb","client","database","db","document","javascript","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wpdas.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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}},"created_at":"2023-07-22T05:56:17.000Z","updated_at":"2025-03-11T21:08:32.000Z","dependencies_parsed_at":"2024-09-25T01:35:00.026Z","dependency_job_id":"32cff8ec-4464-47a5-aed4-56197e1c21ef","html_url":"https://github.com/wpdas/chain-db-ts","commit_stats":null,"previous_names":["wpdas/chain-db-ts"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/wpdas/chain-db-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wpdas","download_url":"https://codeload.github.com/wpdas/chain-db-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wpdas%2Fchain-db-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28767027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T03:54:34.369Z","status":"ssl_error","status_checked_at":"2026-01-26T03:54:33.031Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["chaindb","client","database","db","document","javascript","typescript"],"created_at":"2024-09-24T20:45:47.001Z","updated_at":"2026-01-26T05:06:36.040Z","avatar_url":"https://github.com/wpdas.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chain DB TS / JS Client (Node)\n\nA TypeScript / JavaScript client for [Chain DB](https://github.com/wpdas/chain-db), a secure database system with built-in history tracking, offering AES-256-GCM encryption, atomic operations with rollback capability, and automatic backups.\n\n## Installation\n\n```bash\nnpm install chain-db-ts\n# or\nyarn add chain-db-ts\n```\n\n## Usage\n\n### Creating Database\n\n```typescript\nimport { createDatabase } from 'chain-db-ts'\n\nconst main = async () =\u003e {\n  try {\n    const response = await createDatabase({server: \"http://localhost:2818\", database: \"my-database\", user: \"root\", password: \"1234\"});\n    console.log(response); // Success message\n  } catch (error: any) {\n    console.error('Error creating database:', error.message);\n  }\n}\n```\n\n### Connecting to Database\n\n#### Asynchronously\n\n```typescript\nimport { connect } from 'chain-db-ts'\n\n// Connect to Chain DB async\n// Parameters: server | database | user | password\n// If the server parameter is null, \"http://localhost:2818\" will be used as default\nconst db = await connect({\n  server: 'http://localhost:2818',\n  database: 'my-database',\n  user: 'root',\n  password: '1234',\n})\n```\n\n#### Synchronously\n\nThis is better if you don't want to configure a connection using Promise, which can block the initialization of the application.\n\n```typescript\nimport { connectWithToken } from 'chain-db-ts'\n\n// Connect to Chain DB sync\n// Parameters: server | database | token\n// If the server parameter is null, \"http://localhost:2818\" will be used as default\nconst db = connectWithToken({\n  server: 'http://localhost:2818',\n  database: 'my-database',\n  // Go to https://github.com/wpdas/chain-db?tab=readme-ov-file#authentication to understand how to get this token\n  token: 'dGVzdF9kYjpyb290OjEyMzQ=',\n})\n```\n\n### Working with Tables\n\nDefine your table structure using TypeScript interfaces or types:\n\n```typescript\n// Define your table schema\ninterface GreetingTable {\n  greeting: string\n}\n\n// Define a more complex table schema\ninterface UserTable {\n  id: number\n  name: string\n  email: string\n  active: boolean\n  createdAt: string\n  address: {...}\n}\n```\n\n### Create\n\n```typescript\n// Table Instances\nconst Greeting = db.getTable\u003cGreetingTable\u003e('greetings') // where \"greetings\" is the table name\nconst User = db.getTable\u003cUserTable\u003e('users') // where \"users\" is the table name\n\n// Creates and stores new data into greetings table and returns its content\nconst newGreeting = await Greeting.new({ greeting: \"Hello\" })\n// newGreeting.doc =\u003e { doc_id: \"xyz123\", greeting: \"Hello\" }\n// newGreeting.getTableName() =\u003e \"greetings\"\n// newGreeting.isEmpty() =\u003e true / false\n// await newGreeting.refetch() =\u003e Fetch updated content. This is useful when the data has been changed elsewhere.\n// await newGreeting.update() =\u003e Should be called when you change the newGreeting.doc body\n```\n\n### Get\n\n```typescript\n// Get the last register\nconst greeting = await Greeting.last();\nconsole.log(greeting.doc) // e.g., { doc_id: \"550e8400-e29b-41d4-a716-446655440000\", greeting: \"Hello\" }\n\n// OR\n\n// Get by doc id\nconst docId = '550e8400-e29b-41d4-a716-446655440000'\nconst specificGreeting = await Greeting.getByDocId(docId)\nconsole.log(specificGreeting.doc) // e.g., { doc_id: \"550e8400-e29b-41d4-a716-446655440000\", greeting: \"Hello\" }\n```\n\n### Updating Item\n\n```typescript\ngreeting.doc = { greeting: \"Olá Mundo!\" }; // OR greeting.doc.greeting = \"Olá Mundo!\"\nawait greeting.update()\n```\n\n\u003c!-- Note: The `TableDoc` instance returned by `getByDocId()` is a simplified version of a table that only allows updating the specific document. --\u003e\n\n### Getting Table History\n\n```typescript\n// Get the last 100 changes to the table\nconst history = await Greeting.getHistory(100)\nhistory.forEach(item =\u003e {\n  // Table data instance\n  console.log(item.doc);\n});\n// Example output:\n// { greeting: 'Hello, Chain DB!' },\n// { greeting: 'Hello' },\n// { greeting: 'Hi there' },\n//  ...\n```\n\n### Real-time Events with WebSockets\n\nChain DB supports real-time updates through WebSockets. You can subscribe to table events to get notified when data changes:\n\n```typescript\nimport { EventTypes, EventData } from 'chain-db-ts'\n\n// Subscribe to table update events\ndb.events().subscribe(EventTypes.TABLE_UPDATE, (eventData: EventData) =\u003e {\n  console.log('Table updated:', eventData.table) // e.g. greetings\n  console.log('New data:', eventData.data) // e.g. { greeting: \"Hello World!\" }\n})\n\n// Subscribe to new data persistence events\ndb.events().subscribe(EventTypes.TABLE_PERSIST, (eventData: EventData) =\u003e {\n  console.log('New data added to table:', eventData.table) // e.g. greetings\n  console.log('Data:', eventData.data) // e.g. { greeting: \"Hello World!\" }\n})\n\n// Unsubscribe from an event\nconst myCallback = (eventData: EventData) =\u003e {\n  // Handle event\n}\ndb.events().subscribe(EventTypes.TABLE_UPDATE, myCallback)\n// Later, when you want to unsubscribe:\ndb.events().unsubscribe(EventTypes.TABLE_UPDATE, myCallback)\n\n// Close WebSocket connection when done\ndb.events().closeEvents()\n```\n\nThe `EventData` object contains:\n\n- `event_type`: The type of event (TableUpdate, TablePersist)\n- `database`: The database name\n- `table`: The table name\n- `data`: The data associated with the event\n- `timestamp`: When the event occurred\n\n### Querying Data\n\n#### Basic Queries\n\n```typescript\n// Find items with exact matches\nconst users = await User.findWhere(\n  { active: true, name: 'John' }, // criteria\n  10, // limit (default: 1000)\n  true // reverse order (default: true)\n)\n```\n\n#### Advanced Queries\n\n```typescript\nimport { Operators } from 'chain-db-ts'\n\n// Find items with advanced criteria\nconst users = await User.findWhereAdvanced(\n  [\n    {\n      field: 'name',\n      operator: Operators.CONTAINS,\n      value: 'John',\n    },\n    {\n      field: 'age',\n      operator: Operators.GREATER_THAN,\n      value: 25,\n    },\n  ],\n  10, // limit\n  true // reverse order\n)\n```\n\nAvailable operators:\n\n- `EQUAL` (==)\n- `NOT_EQUAL` (!=)\n- `GREATER_THAN` (\u003e)\n- `GREATER_THAN_OR_EQUAL` (\u003e=)\n- `LESS_THAN` (\u003c)\n- `LESS_THAN_OR_EQUAL` (\u003c=)\n- `CONTAINS` (for strings and arrays)\n- `STARTS_WITH` (for strings)\n- `ENDS_WITH` (for strings)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpdas%2Fchain-db-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwpdas%2Fchain-db-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwpdas%2Fchain-db-ts/lists"}