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

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0-rc.2] - 2025-03-05
+
+### Added
+
+- New `TableDoc` interface for working with specific documents
+- Added `refetch()` method to `TableDoc` to get the latest document data
+- Added `getTableName()` method to `TableDoc` to get the table name
+- Added `isEmpty()` method to `TableDoc` to check if the document is empty
+- Added `DocId<Model>` type that adds a readonly `doc_id` property to models
+- Added `getCurrentDocId()` method to `Table` to get the current document ID
+- The `persist()` method now returns the created document with its `doc_id`
+- Document IDs are now accessible directly via `doc_id` property in both `Table` and `TableDoc` instances
+
+### Changed
+
+- **BREAKING CHANGE**: Renamed `table` property to `currentDoc` in `Table` class for better semantics
+- Improved error messages with more details about the operation and error
+- Enhanced type safety with the `DocId<Model>` type
+
+### Removed
+
+- **BREAKING CHANGE**: Removed `update()` method from `Table` class
+  - To update documents, you must now use `getDoc()` to get a document reference and then call `update()` on that reference
+  - This change prevents accidental creation of duplicate records and makes the API more intuitive
+
+### Migration Guide
+
+#### Property Renaming
+
+Before:
+
+```typescript
+// Accessing table data
+console.log(greetingTable.table)
+
+// Accessing document data from TableDoc
+console.log(specificDoc.table)
+```
+
+After:
+
+```typescript
+// Accessing current document data from Table
+console.log(greetingTable.currentDoc)
+
+// Accessing document data from TableDoc
+console.log(specificDoc.doc)
+```
+
+#### Updating Documents
+
+Before:
+
+```typescript
+// Update the last item
+greetingTable.table.greeting = 'Updated greeting'
+await greetingTable.update()
+
+// Update a specific document by ID
+greetingTable.table.greeting = 'Updated specific document'
+await greetingTable.update('550e8400-e29b-41d4-a716-446655440000')
+```
+
+After:
+
+```typescript
+// Get a specific document by ID
+const specificDoc = await greetingTable.getDoc('550e8400-e29b-41d4-a716-446655440000')
+
+// Update the document
+specificDoc.doc.greeting = 'Updated greeting'
+await specificDoc.update()
+
+// Optionally, refetch the document to get the latest data
+await specificDoc.refetch()
+```
+
+#### Accessing Document IDs
+
+New in this version:
+
+```typescript
+// When persisting data, you get the document ID in the result
+const result = await greetingTable.persist()
+console.log(result.doc_id) // The ID of the newly created document
+
+// You can also get the current document ID directly from the table
+const currentDocId = greetingTable.getCurrentDocId()
+
+// When working with a specific document, the ID is available in multiple ways
+const specificDoc = await greetingTable.getDoc(docId)
+console.log(specificDoc.doc_id) // From the TableDoc instance
+console.log(specificDoc.doc.doc_id) // From the document object
+```
+
+## [1.0.0-rc.1] - 2025-03-01
+
+Initial release candidate.
+
+### Added
+
+- Type-safe API with TypeScript generics
+- Promise-based API with async/await
+- WebSocket support for real-time updates
+- Advanced query capabilities
+- Complete history access

package/dist/cjs/features/chain-db.d.ts

@@ -1,10 +1,10 @@
-import { Access } from './access';
-import { BasicResponse, SignedUserAccount, TransferUnitsRegistry } from './types';
+import Table from './table';
+import { Connection, EventCallback } from './types';
 export declare class ChainDB {
-    api: string;
-    name: string;
-    access: Access | null;
-    access_key: string;
+    server: string;
+    database: string;
+    auth: string;
+    private _events;
     /**
      * Connection information.
      * @param server Server location. If the `server` parameter is empty, then "http://localhost" will be used.
@@ -12,69 +12,28 @@ export declare class ChainDB {
      * @param user  User to access the data base
      * @param password  Password to access the data base
      */
-    connect(server: string | null, data_base: string, user: string, password: string): void;
-    /**
-     * Create a new user account inside the connected table
-     * @param user_name
-     * @param password
-     * @param units
-     * @param password_hint
-     * @returns
-     */
-    create_user_account(user_name: string, password: string, units?: number, password_hint?: string): Promise<BasicResponse<SignedUserAccount>>;
-    /**
-     * Get user account info (login method)
-     * @param user_name
-     * @param password
-     * @returns
-     */
-    get_user_account(user_name: string, password: string): Promise<BasicResponse<SignedUserAccount>>;
-    /**
-     * Get user account info by its id
-     * @param user_id
-     * @returns
-     */
-    get_user_account_by_id(user_id: string): Promise<BasicResponse<SignedUserAccount>>;
-    /**
-     * Check if user_name is already taken
-     * @param user_name
-     */
-    check_user_name(user_name: string): Promise<BasicResponse<string>>;
-    /**
-     * Transfer units between users
-     * @param from user_id
-     * @param to user_id
-     * @param units
-     * @returns
-     */
-    transfer_units(from: string, to: string, units: number): Promise<BasicResponse<null>>;
-    /**
-     * Fetch the last Transference of units Records by User
-     * @param user_id
-     * @returns
-     */
-    get_transfer_by_user_id(user_id: string): Promise<BasicResponse<TransferUnitsRegistry>>;
-    /**
-     * Fetch all Transference of units Records by User
-     * @param user_id
-     * @returns
-     */
-    get_all_transfers_by_user_id(user_id: string): Promise<BasicResponse<TransferUnitsRegistry[]>>;
+    connect(connection: Connection): Promise<void>;
     /**
      * Initialize a table, fetching its more updated data
      */
-    get_table<Model>(table_name: string, model: Model): Promise<{
-        table: Model;
+    getTable<Model>(table_name: string): Promise<Table<Model>>;
+    events(): {
+        /**
+         * Subscribe to an event
+         * @param event Event name to subscribe to @see {EventTypes}
+         * @param callback Function to call when the event is received
+         */
+        subscribe: (event: string, callback: EventCallback) => void;
         /**
-         * Persist table data on chain
+         * Unsubscribe from an event
+         * @param event Event name to unsubscribe from @see {EventTypes}
+         * @param callback Optional callback to remove. If not provided, all callbacks for the event will be removed.
          */
-        persist: () => Promise<void>;
+        unsubscribe: (event: string, callback?: EventCallback) => void;
         /**
-         * Get the history of changes. A list of transactions from the most recent to the most old
-         * in a range of depth
-         * @param depth
+         * Close the events transmission
          */
-        getHistory: (depth: number) => Promise<Model[]>;
-    }>;
+        closeEvents: () => void;
+    };
 }
-export declare const connect: (server: string | null, data_base: string, user: string, password: string) => ChainDB;
+export declare const connect: (connection: Connection) => Promise<ChainDB>;

package/dist/cjs/features/chain-db.js

@@ -1,27 +1,4 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
     return new (P || (P = Promise))(function (resolve, reject) {
@@ -63,18 +40,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 exports.__esModule = true;
 exports.connect = exports.ChainDB = void 0;
-var sha256_1 = __importDefault(require("sha256"));
-var axios_1 = __importDefault(require("axios"));
-var access_1 = require("./access");
 var constants_1 = require("./constants");
 var utils_1 = require("./utils");
-var table = __importStar(require("./table"));
+var table_1 = __importDefault(require("./table"));
+var events_1 = __importDefault(require("./events"));
 var ChainDB = /** @class */ (function () {
     function ChainDB() {
-        this.api = '';
-        this.name = '';
-        this.access = null;
-        this.access_key = '';
+        this.server = constants_1.DEFAULT_API_SERVER;
+        this.database = '';
+        this.auth = '';
+        this._events = null;
     }
     /**
      * Connection information.
@@ -83,224 +58,34 @@ var ChainDB = /** @class */ (function () {
      * @param user  User to access the data base
      * @param password  Password to access the data base
      */
-    ChainDB.prototype.connect = function (server, data_base, user, password) {
-        var key_data = "".concat(data_base).concat(user).concat(password);
-        var key = (0, sha256_1["default"])(key_data);
-        this.api = server || constants_1.API;
-        this.name = data_base;
-        this.access = new access_1.Access(user, password);
-        this.access_key = key;
-    };
-    /**
-     * Create a new user account inside the connected table
-     * @param user_name
-     * @param password
-     * @param units
-     * @param password_hint
-     * @returns
-     */
-    ChainDB.prototype.create_user_account = function (user_name, password, units, password_hint) {
-        return __awaiter(this, void 0, void 0, function () {
-            var url, body, response, _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0:
-                        url = "".concat(this.api).concat(constants_1.CREATE_USER_ACCOUNT);
-                        body = {
-                            db_access_key: this.access_key,
-                            user_name: user_name,
-                            password: password,
-                            password_hint: password_hint,
-                            units: units
-                        };
-                        _b.label = 1;
-                    case 1:
-                        _b.trys.push([1, 4, , 5]);
-                        return [4 /*yield*/, (0, utils_1.post)(url, body)];
-                    case 2:
-                        response = _b.sent();
-                        return [4 /*yield*/, response.data];
-                    case 3: return [2 /*return*/, _b.sent()];
-                    case 4:
-                        _a = _b.sent();
-                        throw new Error('Something went wrong!');
-                    case 5: return [2 /*return*/];
-                }
-            });
-        });
-    };
-    /**
-     * Get user account info (login method)
-     * @param user_name
-     * @param password
-     * @returns
-     */
-    ChainDB.prototype.get_user_account = function (user_name, password) {
-        return __awaiter(this, void 0, void 0, function () {
-            var url, response, _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0:
-                        url = "".concat(this.api).concat(constants_1.GET_USER_ACCOUNT, "/").concat(user_name, "/").concat(password, "/").concat(this.access_key);
-                        _b.label = 1;
-                    case 1:
-                        _b.trys.push([1, 4, , 5]);
-                        return [4 /*yield*/, axios_1["default"].get(url)];
-                    case 2:
-                        response = _b.sent();
-                        return [4 /*yield*/, response.data];
-                    case 3: return [2 /*return*/, _b.sent()];
-                    case 4:
-                        _a = _b.sent();
-                        throw new Error('Something went wrong!');
-                    case 5: return [2 /*return*/];
-                }
-            });
-        });
-    };
-    /**
-     * Get user account info by its id
-     * @param user_id
-     * @returns
-     */
-    ChainDB.prototype.get_user_account_by_id = function (user_id) {
+    ChainDB.prototype.connect = function (connection) {
         return __awaiter(this, void 0, void 0, function () {
-            var url, response, _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0:
-                        url = "".concat(this.api).concat(constants_1.GET_USER_ACCOUNT_BY_ID, "/").concat(user_id, "/").concat(this.access_key);
-                        _b.label = 1;
-                    case 1:
-                        _b.trys.push([1, 4, , 5]);
-                        return [4 /*yield*/, axios_1["default"].get(url)];
-                    case 2:
-                        response = _b.sent();
-                        return [4 /*yield*/, response.data];
-                    case 3: return [2 /*return*/, _b.sent()];
-                    case 4:
-                        _a = _b.sent();
-                        throw new Error('Something went wrong!');
-                    case 5: return [2 /*return*/];
-                }
-            });
-        });
-    };
-    /**
-     * Check if user_name is already taken
-     * @param user_name
-     */
-    ChainDB.prototype.check_user_name = function (user_name) {
-        return __awaiter(this, void 0, void 0, function () {
-            var url, response, _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0:
-                        url = "".concat(this.api).concat(constants_1.CHECK_USER_NAME, "/").concat(user_name, "/").concat(this.access_key);
-                        _b.label = 1;
-                    case 1:
-                        _b.trys.push([1, 4, , 5]);
-                        return [4 /*yield*/, axios_1["default"].get(url)];
-                    case 2:
-                        response = _b.sent();
-                        return [4 /*yield*/, response.data];
-                    case 3: return [2 /*return*/, _b.sent()];
-                    case 4:
-                        _a = _b.sent();
-                        throw new Error('Something went wrong!');
-                    case 5: return [2 /*return*/];
-                }
-            });
-        });
-    };
-    /**
-     * Transfer units between users
-     * @param from user_id
-     * @param to user_id
-     * @param units
-     * @returns
-     */
-    ChainDB.prototype.transfer_units = function (from, to, units) {
-        return __awaiter(this, void 0, void 0, function () {
-            var url, body, response, _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0:
-                        url = "".concat(this.api).concat(constants_1.TRANSFER_UNITS);
-                        body = {
-                            db_access_key: this.access_key,
-                            from: from,
-                            to: to,
-                            units: units
-                        };
-                        _b.label = 1;
-                    case 1:
-                        _b.trys.push([1, 4, , 5]);
-                        return [4 /*yield*/, (0, utils_1.post)(url, body)];
-                    case 2:
-                        response = _b.sent();
-                        return [4 /*yield*/, response.data];
-                    case 3: return [2 /*return*/, _b.sent()];
-                    case 4:
-                        _a = _b.sent();
-                        throw new Error('Something went wrong!');
-                    case 5: return [2 /*return*/];
-                }
-            });
-        });
-    };
-    /**
-     * Fetch the last Transference of units Records by User
-     * @param user_id
-     * @returns
-     */
-    ChainDB.prototype.get_transfer_by_user_id = function (user_id) {
-        return __awaiter(this, void 0, void 0, function () {
-            var url, response, _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
-                    case 0:
-                        url = "".concat(this.api).concat(constants_1.GET_TRANSFER_BY_USER_ID, "/").concat(user_id, "/").concat(this.access_key);
-                        _b.label = 1;
-                    case 1:
-                        _b.trys.push([1, 4, , 5]);
-                        return [4 /*yield*/, axios_1["default"].get(url)];
-                    case 2:
-                        response = _b.sent();
-                        return [4 /*yield*/, response.data];
-                    case 3: return [2 /*return*/, _b.sent()];
-                    case 4:
-                        _a = _b.sent();
-                        throw new Error('Something went wrong!');
-                    case 5: return [2 /*return*/];
-                }
-            });
-        });
-    };
-    /**
-     * Fetch all Transference of units Records by User
-     * @param user_id
-     * @returns
-     */
-    ChainDB.prototype.get_all_transfers_by_user_id = function (user_id) {
-        return __awaiter(this, void 0, void 0, function () {
-            var url, response, _a;
-            return __generator(this, function (_b) {
-                switch (_b.label) {
+            var server, database, user, password, response, e_1;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
                     case 0:
-                        url = "".concat(this.api).concat(constants_1.GET_ALL_TRANSFER_BY_USER_ID, "/").concat(user_id, "/").concat(this.access_key);
-                        _b.label = 1;
+                        server = connection.server, database = connection.database, user = connection.user, password = connection.password;
+                        this.server = server || constants_1.DEFAULT_API_SERVER;
+                        this.database = database;
+                        _a.label = 1;
                     case 1:
-                        _b.trys.push([1, 4, , 5]);
-                        return [4 /*yield*/, axios_1["default"].get(url)];
+                        _a.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, (0, utils_1.post)("".concat(this.server).concat(constants_1.CONNECT), {
+                                name: this.database,
+                                user: user,
+                                password: password
+                            })];
                     case 2:
-                        response = _b.sent();
-                        return [4 /*yield*/, response.data];
-                    case 3: return [2 /*return*/, _b.sent()];
-                    case 4:
-                        _a = _b.sent();
-                        throw new Error('Something went wrong!');
-                    case 5: return [2 /*return*/];
+                        response = _a.sent();
+                        if (!response.data.success) {
+                            throw new Error(response.data.message);
+                        }
+                        this.auth = response.data.data;
+                        return [3 /*break*/, 4];
+                    case 3:
+                        e_1 = _a.sent();
+                        throw new Error("Something went wrong! ".concat(e_1.message || String(e_1)));
+                    case 4: return [2 /*return*/];
                 }
             });
         });
@@ -308,40 +93,92 @@ var ChainDB = /** @class */ (function () {
     /**
      * Initialize a table, fetching its more updated data
      */
-    ChainDB.prototype.get_table = function (table_name, model) {
+    ChainDB.prototype.getTable = function (table_name) {
         return __awaiter(this, void 0, void 0, function () {
-            var chainDbCopy, table_data;
+            var tableData;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0:
-                        chainDbCopy = (0, exports.connect)(this.api, this.name, this.access.user, this.access.password);
-                        return [4 /*yield*/, table.get(chainDbCopy, table_name, model)
+                        tableData = new table_1["default"](table_name, this);
+                        return [4 /*yield*/, tableData.refetch()];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/, tableData
+                            // const table_data = await table.get<Model>(this, table_name, model)
                             // NOTE: Although only the "table" and "persist" properties are displayed by
                             // the lint, all Table properties are being exposed.
                             // This is due to a javascript limitation on classes.
                             //
                             // There was an attempt to return a new object with only the required
                             // data, but this generates an error in the "this" instance of the Table.
+                            // return table_data as {
+                            //   table: Model
+                            //   /**
+                            //    * Persist table data on chain
+                            //    */
+                            //   persist: () => Promise<void>
+                            //   /**
+                            //    * Get the history of changes. A list of transactions from the most recent to the most old
+                            //    * in a range of depth
+                            //    * @param depth
+                            //    */
+                            //   getHistory: (depth: number) => Promise<Model[]>
+                            // }
                         ];
-                    case 1:
-                        table_data = _a.sent();
-                        // NOTE: Although only the "table" and "persist" properties are displayed by
-                        // the lint, all Table properties are being exposed.
-                        // This is due to a javascript limitation on classes.
-                        //
-                        // There was an attempt to return a new object with only the required
-                        // data, but this generates an error in the "this" instance of the Table.
-                        return [2 /*return*/, table_data];
                 }
             });
         });
     };
+    ChainDB.prototype.events = function () {
+        var _this = this;
+        return {
+            /**
+             * Subscribe to an event
+             * @param event Event name to subscribe to @see {EventTypes}
+             * @param callback Function to call when the event is received
+             */
+            subscribe: function (event, callback) {
+                var _a;
+                if (_this._events === null) {
+                    var wsUrl = "".concat(_this.server.replace('http', 'ws')).concat(constants_1.WEB_SOCKET_EVENTS);
+                    _this._events = new events_1["default"](wsUrl, _this.auth);
+                }
+                (_a = _this._events) === null || _a === void 0 ? void 0 : _a.subscribe(event, callback);
+            },
+            /**
+             * Unsubscribe from an event
+             * @param event Event name to unsubscribe from @see {EventTypes}
+             * @param callback Optional callback to remove. If not provided, all callbacks for the event will be removed.
+             */
+            unsubscribe: function (event, callback) {
+                if (!_this._events || !_this._events.isConnected()) {
+                    return;
+                }
+                _this._events.unsubscribe(event, callback);
+            },
+            /**
+             * Close the events transmission
+             */
+            closeEvents: function () {
+                var _a;
+                (_a = _this._events) === null || _a === void 0 ? void 0 : _a.close();
+            }
+        };
+    };
     return ChainDB;
 }());
 exports.ChainDB = ChainDB;
-var connect = function (server, data_base, user, password) {
-    var chainDb = new ChainDB();
-    chainDb.connect(server, data_base, user, password);
-    return chainDb;
-};
+var connect = function (connection) { return __awaiter(void 0, void 0, void 0, function () {
+    var chainDb;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                chainDb = new ChainDB();
+                return [4 /*yield*/, chainDb.connect(connection)];
+            case 1:
+                _a.sent();
+                return [2 /*return*/, chainDb];
+        }
+    });
+}); };
 exports.connect = connect;

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

@@ -1,11 +1,11 @@
-export declare const API = "http://localhost:2818";
-export declare const CONTRACT_PAYLOAD = "/get_last_contract_transaction";
-export declare const CONTRACT_TRANSACTIONS_PAYLOAD = "/get_contract_transactions";
-export declare const CONTRACT_TRANSACTION = "/post_contract_transaction";
-export declare const CREATE_USER_ACCOUNT = "/create_user_account";
-export declare const GET_USER_ACCOUNT = "/get_user_account";
-export declare const GET_USER_ACCOUNT_BY_ID = "/get_user_account_by_id";
-export declare const TRANSFER_UNITS = "/transfer_units";
-export declare const GET_TRANSFER_BY_USER_ID = "/get_transfer_by_user_id";
-export declare const GET_ALL_TRANSFER_BY_USER_ID = "/get_all_transfers_by_user_id";
-export declare const CHECK_USER_NAME = "/check_user_name";
+export declare const DEFAULT_API_SERVER = "http://localhost:2818";
+export declare const API_BASE = "/api/v1";
+export declare const CONNECT: string;
+export declare const GET_TABLE: (table: string) => string;
+export declare const UPDATE_ITEM: (table: string) => string;
+export declare const PERSIST_NEW_DATA: (table: string) => string;
+export declare const GET_HISTORY: (table: string, limit?: number) => string;
+export declare const FIND_WHERE_BASIC: (table: string) => string;
+export declare const FIND_WHERE_ADVANCED: (table: string) => string;
+export declare const GET_DOC: (table: string, doc_id: string) => string;
+export declare const WEB_SOCKET_EVENTS: string;