chain-db-ts 0.0.2 → 1.0.0-rc.2

package/features/types.js

@@ -1,7 +1,29 @@
-export var TransactionType;
-(function (TransactionType) {
-    TransactionType["NONE"] = "NONE";
-    TransactionType["ACCOUNT"] = "ACCOUNT";
-    TransactionType["CONTRACT"] = "CONTRACT";
-    TransactionType["TRANSFER"] = "TRANSFER";
-})(TransactionType || (TransactionType = {}));
+/**
+ * Operators for the advanced criteria
+ * @see https://docs.chaindb.com/docs/query-language/ (TODO)
+ */
+export var Operators = {
+    // (==)
+    EQUAL: 'Eq',
+    // (!=)
+    NOT_EQUAL: 'Ne',
+    // (>)
+    GREATER_THAN: 'Gt',
+    // (>=)
+    GREATER_THAN_OR_EQUAL: 'Ge',
+    // (<)
+    LESS_THAN: 'Lt',
+    // (<=)
+    LESS_THAN_OR_EQUAL: 'Le',
+    // (for strings and arrays)
+    CONTAINS: 'Contains',
+    // (for strings)
+    STARTS_WITH: 'StartsWith',
+    // (for strings)
+    ENDS_WITH: 'EndsWith'
+};
+// Events
+export var EventTypes = {
+    TABLE_PERSIST: 'TablePersist',
+    TABLE_UPDATE: 'TableUpdate'
+};

package/features/utils.d.ts

@@ -1 +1,2 @@
-export declare const post: (url: string, body: any) => Promise<import("axios").AxiosResponse<any, any>>;
+import { BasicResponse } from './types';
+export declare const post: (url: string, body: any, auth?: string) => Promise<import("axios").AxiosResponse<BasicResponse<any>, any>>;

package/features/utils.js

@@ -1,4 +1,7 @@
 import axios from 'axios';
-export var post = function (url, body) {
-    return axios.post(url, body, { headers: { 'content-type': 'application/json' } });
+export var post = function (url, body, auth) {
+    if (auth === void 0) { auth = ''; }
+    return axios.post(url, body, {
+        headers: { 'content-type': 'application/json', Authorization: "Basic ".concat(auth) }
+    });
 };

package/index.d.ts

@@ -1,3 +1,4 @@
 export { ChainDB, connect } from './features/chain-db';
-export { Access } from './features/access';
-export { BasicResponse, SignedUserAccount } from './features/types';
+export { BasicResponse, Operators, CriteriaAdvanced, Criteria, TableDoc, EventTypes, EventData, EventCallback, } from './features/types';
+export { default as Events } from './features/events';
+export { TableDocImpl } from './features/table-doc';

package/index.js

@@ -1,2 +1,4 @@
 export { ChainDB, connect } from './features/chain-db';
-export { Access } from './features/access';
+export { Operators, EventTypes, } from './features/types';
+export { default as Events } from './features/events';
+export { TableDocImpl } from './features/table-doc';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chain-db-ts",
-  "version": "0.0.2",
+  "version": "1.0.0-rc.2",
   "description": "Chain DB Client for Javascript/Typescript Node apps.",
   "main": "./dist/cjs/index.js",
   "module": "./index.js",
@@ -26,7 +26,7 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^18.15.5",
-    "@types/sha256": "^0.2.0",
+    "@types/ws": "^8.5.14",
     "nodemon": "^3.0.1",
     "ts-node": "^10.9.1",
     "tslib": "^2.5.0",
@@ -35,6 +35,8 @@
   "repository": "git://github.com/wpdas/chain-db-ts.git",
   "dependencies": {
     "axios": "^1.4.0",
-    "sha256": "^0.2.0"
+    "bufferutil": "^4.0.9",
+    "utf-8-validate": "^6.0.5",
+    "ws": "^8.18.1"
   }
 }

package/readme.md

@@ -1,186 +1,314 @@
-# Chain DB - TS
+# Chain DB TypeScript Client
 
-ChainDB TS is a library that allows the usage of the ChainDB database in TypeScript and JavaScript projects.
+A TypeScript client for [Chain DB](https://github.com/wpdas/chain-db), a simple database that maintains a history of changes, allowing you to track how your data evolves over time.
 
-Chain DB is a Story-driven database. This new type of system uses some features used in blockchain technology. Each change generates a transaction that is saved in a block. The network works centrally, so persistent data is not decentralized.
+## Installation
 
-This database has some features by default, such as: create user account, get user account, transfer units and get transfer records as well as the main feature that is tables.
+```bash
+npm install chain-db-ts
+# or
+yarn add chain-db-ts
+```
 
-The `unit` property present in each user's account can be anything the project wants, it can be a type of currency, item, resource.
+## Usage
 
-Visit the [Chain DB repository](https://github.com/wpdas/chain-db) to get to know more.
+### Connecting to Chain DB
 
-## Install
+```typescript
+import { connect } from 'chain-db-ts'
 
-Install using npm or yarn:
+// Connect to Chain DB
+// Parameters: server | database | user | password
+// If the server parameter is null, "http://localhost:2818" will be used as default
+const db = await connect({
+  server: 'http://localhost:2818',
+  database: 'my-database',
+  user: 'root',
+  password: '1234',
+})
+```
 
-```sh
-npm install chain-db-ts
+### Working with Tables
 
-# or
+Define your table structure using TypeScript interfaces:
 
-yarn add chain-db-ts
+```typescript
+// Define your table structure
+interface GreetingTable {
+  greeting: string
+}
+
+// Define a more complex table
+interface UserTable {
+  id: number
+  name: string
+  email: string
+  active: boolean
+  createdAt: string
+}
 ```
 
-## Usage examples
+### Getting a Table
 
-First of all, it's good to know that all requests return a `BasicResponse<D>` object that has the following structure:
+```typescript
+// Get a table instance
+// If the table already exists in the chain, its data will be loaded. (data from the last record stored in the table)
+const greetingTable = await db.getTable<GreetingTable>('greeting')
 
-**success:** `boolean` (informs if the transaction was successful) <br/>
-**error_msg:** `string` (error message) <br/>
-**data:** `D` (any expected data type depending on the request) <br/>
+// Access the current document data (the last record stored in the table)
+console.log(greetingTable.currentDoc) // e.g., { greeting: 'Hello' }
+```
 
-Make sure you have the database running on your local machine or use the server link from where the database is running.
+### Modifying and Persisting Data
 
-### Table
+```typescript
+// Modify the current document data
+greetingTable.currentDoc.greeting = 'Hello, Chain DB!'
 
-Tables must be simple class with default values, empty or not. This class will be used as a reference to create the table's fields.
+// Persist changes to database (creates a new record with a new doc_id)
+const result = await greetingTable.persist()
 
-When it's time to persist the table's data on the chain, just call the `persit` database function.
+// The persist method returns the created document with its doc_id
+console.log(result.doc_id) // e.g., '550e8400-e29b-41d4-a716-446655440000'
 
-```ts
-// Greeting Table
-class GreetingTable {
-  public greeting = 'Hi'
-}
+// You can also access the current document's ID directly
+const currentDocId = greetingTable.getCurrentDocId()
+console.log(currentDocId) // Same as result.doc_id
 ```
 
-```ts
-import { connect } from 'chain-db-ts'
-import { GreetingTable } from './tables'
-
-const main async () {
-  // server | db-name | user | password
-  // If the `server` parameter is empty(null), then "http://localhost:2818" will be used.
-  const db = connect('http://localhost:2818', 'test-db', 'root', '1234')
+### Updating Item
 
-  // Initialize the "greeting" table using the "GreetingTable"
-  // class as a template. If there is already any data saved in
-  // the chain, this data will be populated in the table instance.
-  const greetingTable = await db.get_table('greeting', new GreetingTable())
-  console.log(greetingTable.table) // { greeting: 'Hi' }
+```typescript
+// To update a specific document, first get it by ID
+const docId = '550e8400-e29b-41d4-a716-446655440000'
+const specificDoc = await greetingTable.getDoc(docId)
 
-  // Mutating data
-  greetingTable.table.greeting = "Hello my dear!"
-  await greetingTable.persist() // Data is persisted on the blockchain
-
-  // See the most updated values of the table
-  console.log(greetingTable.table) // { greeting: 'Hello my dear!' }
-}
-main()
+// Then update its data
+specificDoc.doc.greeting = 'Updated greeting'
+await specificDoc.update()
 ```
 
-The next examples will not include the `db` implementation, ` import` lines and the `const main async () {}` block as this is implied.
+### Getting a Specific Document
 
-### Create User Account
+```typescript
+// Get a specific document by its ID (assuming we know a document ID)
+// The document ID is generated by ChainDB when data is persisted
+const docId = '550e8400-e29b-41d4-a716-446655440000' // Example ID
+const specificDoc = await greetingTable.getDoc(docId)
 
-This is a default database feature that allows you to create user accounts within the database. As these are hashed accounts, the only data required is: Username and Password. This data is hashed, that is, only the user with the correct data can access the data.
+// Access the document data
+console.log(specificDoc.doc) // e.g., { greeting: 'Hello from specific doc', doc_id: '550e8400-e29b-41d4-a716-446655440000' }
 
-It is not possible to recover an account in which the user has forgotten access data.
+// The doc_id is also available directly in the document object
+console.log(specificDoc.doc.doc_id) // '550e8400-e29b-41d4-a716-446655440000'
 
-```ts
-const user_name = 'wenderson.fake'
-const user_pass = '1234'
+// Update the specific document
+specificDoc.doc.greeting = 'Updated greeting for specific doc'
+await specificDoc.update() // Updates only this specific document
 
-// Check if the given name is already in use
-const user_name_taken = await db.check_user_name(user_name)
-if (!user_name_taken.success) {
-  // user name | password | units (optional) | password hint (optional - may be used in the future versions)
-  const user = await db.create_user_account(user_name, user_pass, 2)
-  console.log(user.data)
-  // {
-  //   id: 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3',
-  //   user_name: 'wenderson.fake',
-  //   units: 2
-  // }
-}
+// Refetch the document data if it might have been updated elsewhere
+await specificDoc.refetch()
+console.log(specificDoc.doc) // Updated data from the database
+
+// Get the table name this document belongs to
+const tableName = specificDoc.getTableName() // 'greeting'
 ```
 
-### Get User Account Info
+Note: The `TableDoc` instance returned by `getDoc()` is a simplified version of a table that only allows updating the specific document. It cannot create new records with `persist()` or perform other table operations.
 
-This feature can be used for the "Login/Sign In" action.
+### Getting Table History
 
-```ts
-const user_name = 'wenderson.fake'
-const user_pass = '1234'
-const user = await db.get_user_account(user_name, user_pass)
-console.log(user.data)
-// {
-//   id: 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3',
-//   user_name: 'wenderson.fake',
-//   units: 2
-// }
+```typescript
+// Get the last 100 changes to the table
+const history = await greetingTable.getHistory(100)
+console.log(history)
+// Example output:
+// [
+//   { greeting: 'Hello, Chain DB!' },
+//   { greeting: 'Hello' },
+//   { greeting: 'Hi there' },
+//   ...
+// ]
 ```
 
-### Get User Account Info By User Id
+### Real-time Events with WebSockets
+
+Chain DB supports real-time updates through WebSockets. You can subscribe to table events to get notified when data changes:
 
-Just another way to fetch the user info.
+```typescript
+import { EventTypes, EventData } from 'chain-db-ts'
 
-```ts
-const wenderson_id = 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3'
-const user = await db.get_user_account_by_id(wenderson_id)
-console.log(user.data)
-// {
-//   id: 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3',
-//   user_name: 'wenderson.fake',
-//   units: 2
-// }
+// Subscribe to table update events
+db.events().subscribe(EventTypes.TABLE_UPDATE, (eventData: EventData) => {
+  console.log('Table updated:', eventData.table)
+  console.log('New data:', eventData.data)
+})
+
+// Subscribe to new data persistence events
+db.events().subscribe(EventTypes.TABLE_PERSIST, (eventData: EventData) => {
+  console.log('New data added to table:', eventData.table)
+  console.log('Data:', eventData.data)
+})
+
+// Unsubscribe from an event
+const myCallback = (eventData: EventData) => {
+  // Handle event
+}
+db.events().subscribe(EventTypes.TABLE_UPDATE, myCallback)
+// Later, when you want to unsubscribe:
+db.events().unsubscribe(EventTypes.TABLE_UPDATE, myCallback)
+
+// Close WebSocket connection when done
+db.events().closeEvents()
 ```
 
-### Transfer Units Between Two Users
+The `EventData` object contains:
 
-As said before, `unit` property present in each user's account can be anything the project wants, it can be a type of currency, item, resource.
+- `event_type`: The type of event (TableUpdate, TablePersist)
+- `database`: The database name
+- `table`: The table name
+- `data`: The data associated with the event
+- `timestamp`: When the event occurred
 
-Below is an example of user `wenderson` trying to send 2 units to `suly`:
+### Querying Data
 
-```ts
-const wenderson_id = 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3'
-const suly_id = '136c406933d98e5c8bb4820f5145869bb5ad40647b768de4e9adb2a52d0dea2f'
+#### Basic Queries
 
-const wenderson_data = await db.get_user_account_by_id(wenderson_id)
-const units_to_transfer = 2
+```typescript
+// Find items with exact matches
+const users = await userTable.findWhere(
+  { active: true, name: 'John' }, // criteria
+  10, // limit (default: 1000)
+  true // reverse order (default: true)
+)
+```
 
-if (wenderson_data.data!.units >= units_to_transfer) {
-  const res = await db.transfer_units(wenderson_id, suly_id, units_to_transfer)
-  console.log(res.success)
-  // true / false
-}
+#### Advanced Queries
+
+```typescript
+import { Operators } from 'chain-db-ts'
+
+// Find items with advanced criteria
+const users = await userTable.findWhereAdvanced(
+  [
+    {
+      field: 'name',
+      operator: Operators.CONTAINS,
+      value: 'John',
+    },
+    {
+      field: 'age',
+      operator: Operators.GREATER_THAN,
+      value: 25,
+    },
+  ],
+  10, // limit
+  true // reverse order
+)
 ```
 
-### Fetching the Latest Units Transfer Record
+Available operators:
+
+- `EQUAL` (==)
+- `NOT_EQUAL` (!=)
+- `GREATER_THAN` (>)
+- `GREATER_THAN_OR_EQUAL` (>=)
+- `LESS_THAN` (<)
+- `LESS_THAN_OR_EQUAL` (<=)
+- `CONTAINS` (for strings and arrays)
+- `STARTS_WITH` (for strings)
+- `ENDS_WITH` (for strings)
+
+### Other Table Methods
 
-Use this feature to get the last unit transfer record involving a user.
+```typescript
+// Check if a table is empty
+const isEmpty = greetingTable.isEmpty()
 
-```ts
-const wenderson_id = 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3'
-const last_units_transference_record = await db.get_transfer_by_user_id(wenderson_id)
-console.log(last_units_transference_record.data)
-// {
-//   from: 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3',
-//   to: '136c406933d98e5c8bb4820f5145869bb5ad40647b768de4e9adb2a52d0dea2f',
-//   units: 2
-// }
+// Get the table name
+const tableName = greetingTable.getName()
+
+// Refetch the table data from the database
+await greetingTable.refetch()
 ```
 
-### Fetching All the Transfer of Units Records
+## Complete Example
 
-Use this feature to get the last unit transfer record involving a user.
+```typescript
+import { connect, EventTypes, EventData } from 'chain-db-ts'
 
-```ts
-const wenderson_id = 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3'
-const all_units_transfers_record = await db.get_all_transfers_by_user_id(wenderson_id)
-console.log(all_units_transfers_record.data)
-// [
-//   {
-//     from: 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3',
-//     to: '136c406933d98e5c8bb4820f5145869bb5ad40647b768de4e9adb2a52d0dea2f',
-//     units: 2
-//   },
-//   {
-//     from: '136c406933d98e5c8bb4820f5145869bb5ad40647b768de4e9adb2a52d0dea2f',
-//     to: 'b2e4e7c15f733d8c18836ffd22051ed855226d9041fb9452f17f498fc2bcbce3',
-//     units: 6
-//   },
-//   ...
-// ]
+// Define table structure
+interface GreetingTable {
+  greeting: string
+}
+
+async function main() {
+  // Connect to Chain DB
+  const db = await connect({
+    server: 'http://localhost:2818',
+    database: 'test-db',
+    user: 'root',
+    password: '1234',
+  })
+
+  // Get the "greeting" table
+  const greetingTable = await db.getTable<GreetingTable>('greeting')
+  console.log(greetingTable.currentDoc) // e.g., { greeting: 'Hi' }
+
+  // Subscribe to table update events
+  db.events().subscribe(EventTypes.TABLE_UPDATE, (eventData: EventData) => {
+    if (eventData.table === 'greeting') {
+      console.log('Greeting table updated:', eventData.data)
+    }
+  })
+
+  // Modify and persist data
+  greetingTable.currentDoc.greeting = 'Hello my dear!'
+  const persistResult = await greetingTable.persist() // Data is persisted on database
+
+  // Get the doc_id of the newly created document
+  console.log('New document ID:', persistResult.doc_id)
+
+  // You can also get the current document ID directly from the table
+  const currentDocId = greetingTable.getCurrentDocId()
+  console.log('Current document ID:', currentDocId)
+
+  // See the updated values
+  console.log(greetingTable.currentDoc) // { greeting: 'Hello my dear!', doc_id: '...' }
+
+  // Get a specific document by its ID
+  // We can use the ID we just got from the persist operation
+  const specificDoc = await greetingTable.getDoc(currentDocId)
+
+  // Access the document data and ID
+  console.log(specificDoc.doc) // { greeting: 'Hello my dear!', doc_id: '...' }
+  console.log(specificDoc.doc.doc_id) // Same as currentDocId
+
+  // Update a specific document
+  specificDoc.doc.greeting = 'Updated specific document'
+  await specificDoc.update() // Updates only this specific document
+
+  // Refetch the document to get the latest data
+  await specificDoc.refetch()
+  console.log(specificDoc.doc) // Latest data from the database
+
+  // Get the last 100 changes
+  const greetingHistory = await greetingTable.getHistory(100)
+  console.log(greetingHistory)
+  // [
+  //   { greeting: 'Updated specific document' },
+  //   { greeting: 'Hello my dear!' },
+  //   { greeting: 'Hi' },
+  //   ...
+  // ]
+
+  // Close WebSocket connection when done
+  db.events().closeEvents()
+}
+
+main().catch(console.error)
 ```
+
+## License
+
+MIT

package/dist/cjs/features/access.d.ts

@@ -1,6 +0,0 @@
-export declare class Access {
-    user: string;
-    password: string;
-    constructor(user: string, password: string);
-    parse: (data_base: string, table_name: string) => string;
-}

package/dist/cjs/features/access.js

@@ -1,22 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-exports.__esModule = true;
-exports.Access = void 0;
-var sha256_1 = __importDefault(require("sha256"));
-var Access = /** @class */ (function () {
-    function Access(user, password) {
-        var _this = this;
-        this.user = '';
-        this.password = '';
-        this.parse = function (data_base, table_name) {
-            var access_info = "".concat(data_base).concat(table_name).concat(_this.user).concat(_this.password);
-            return (0, sha256_1["default"])(access_info);
-        };
-        this.user = user;
-        this.password = password;
-    }
-    return Access;
-}());
-exports.Access = Access;

package/features/access.d.ts

@@ -1,6 +0,0 @@
-export declare class Access {
-    user: string;
-    password: string;
-    constructor(user: string, password: string);
-    parse: (data_base: string, table_name: string) => string;
-}

package/features/access.js

@@ -1,16 +0,0 @@
-import sha256 from 'sha256';
-var Access = /** @class */ (function () {
-    function Access(user, password) {
-        var _this = this;
-        this.user = '';
-        this.password = '';
-        this.parse = function (data_base, table_name) {
-            var access_info = "".concat(data_base).concat(table_name).concat(_this.user).concat(_this.password);
-            return sha256(access_info);
-        };
-        this.user = user;
-        this.password = password;
-    }
-    return Access;
-}());
-export { Access };