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

package/readme.md

@@ -1,6 +1,6 @@
-# Chain DB TypeScript Client
+# Chain DB TS / JS Client (Node)
 
-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.
+A 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.
 
 ## Installation
 
@@ -14,10 +14,12 @@ yarn add chain-db-ts
 
 ### Connecting to Chain DB
 
+#### Asynchronously
+
 ```typescript
 import { connect } from 'chain-db-ts'
 
-// Connect to Chain DB
+// Connect to Chain DB async
 // Parameters: server | database | user | password
 // If the server parameter is null, "http://localhost:2818" will be used as default
 const db = await connect({
@@ -28,107 +30,99 @@ const db = await connect({
 })
 ```
 
+#### Synchronously
+
+This is better if you don't want to configure a connection using Promise, which can block the initialization of the application.
+
+```typescript
+import { connectWithToken } from 'chain-db-ts'
+
+// Connect to Chain DB sync
+// Parameters: server | database | token
+// If the server parameter is null, "http://localhost:2818" will be used as default
+const db = connectWithToken({
+  server: 'http://localhost:2818',
+  database: 'my-database',
+  // Go to https://github.com/wpdas/chain-db?tab=readme-ov-file#authentication to understand how to get this token
+  token: 'dGVzdF9kYjpyb290OjEyMzQ=',
+})
+```
+
 ### Working with Tables
 
-Define your table structure using TypeScript interfaces:
+Define your table structure using TypeScript interfaces or types:
 
 ```typescript
-// Define your table structure
+// Define your table schema
 interface GreetingTable {
   greeting: string
 }
 
-// Define a more complex table
+// Define a more complex table schema
 interface UserTable {
   id: number
   name: string
   email: string
   active: boolean
   createdAt: string
+  address: {...}
 }
 ```
 
-### Getting a Table
+### Create
 
 ```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')
-
-// Access the current document data (the last record stored in the table)
-console.log(greetingTable.currentDoc) // e.g., { greeting: 'Hello' }
+// Table Instances
+const Greeting = db.getTable<GreetingTable>('greetings') // where "greetings" is the table name
+const User = db.getTable<UserTable>('users') // where "users" is the table name
+
+// Creates and stores new data into greetings table and returns its content
+const newGreeting = await Greeting.new({ greeting: "Hello" })
+// newGreeting.doc => { doc_id: "xyz123", greeting: "Hello" }
+// newGreeting.getTableName() => "greetings"
+// newGreeting.isEmpty() => true / false
+// await newGreeting.refetch() => Fetch updated content. This is useful when the data has been changed elsewhere.
+// await newGreeting.update() => Should be called when you change the newGreeting.doc body
 ```
 
-### Modifying and Persisting Data
+### Get
 
 ```typescript
-// Modify the current document data
-greetingTable.currentDoc.greeting = 'Hello, Chain DB!'
-
-// Persist changes to database (creates a new record with a new doc_id)
-const result = await greetingTable.persist()
-
-// The persist method returns the created document with its doc_id
-console.log(result.doc_id) // e.g., '550e8400-e29b-41d4-a716-446655440000'
-
-// You can also access the current document's ID directly
-const currentDocId = greetingTable.getCurrentDocId()
-console.log(currentDocId) // Same as result.doc_id
-```
+// Get the last register
+const greeting = await Greeting.last();
+console.log(greeting.doc) // e.g., { doc_id: "550e8400-e29b-41d4-a716-446655440000", greeting: "Hello" }
 
-### Updating Item
+// OR
 
-```typescript
-// To update a specific document, first get it by ID
+// Get by doc id
 const docId = '550e8400-e29b-41d4-a716-446655440000'
-const specificDoc = await greetingTable.getDoc(docId)
-
-// Then update its data
-specificDoc.doc.greeting = 'Updated greeting'
-await specificDoc.update()
+const specificGreeting = await Greeting.getByDocId(docId)
+console.log(specificGreeting.doc) // e.g., { doc_id: "550e8400-e29b-41d4-a716-446655440000", greeting: "Hello" }
 ```
 
-### Getting a Specific Document
+### Updating Item
 
 ```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)
-
-// Access the document data
-console.log(specificDoc.doc) // e.g., { greeting: 'Hello from specific doc', doc_id: '550e8400-e29b-41d4-a716-446655440000' }
-
-// The doc_id is also available directly in the document object
-console.log(specificDoc.doc.doc_id) // '550e8400-e29b-41d4-a716-446655440000'
-
-// Update the specific document
-specificDoc.doc.greeting = 'Updated greeting for specific doc'
-await specificDoc.update() // Updates only this specific document
-
-// 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'
+greeting.doc = { greeting: "Olá Mundo!" }; // OR greeting.doc.greeting = "Olá Mundo!"
+await greeting.update()
 ```
 
-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.
+<!-- Note: The `TableDoc` instance returned by `getByDocId()` is a simplified version of a table that only allows updating the specific document. -->
 
 ### Getting Table History
 
 ```typescript
 // Get the last 100 changes to the table
-const history = await greetingTable.getHistory(100)
-console.log(history)
+const history = await Greeting.getHistory(100)
+history.forEach(item => {
+  // Table data instance
+  console.log(item.doc);
+});
 // Example output:
-// [
-//   { greeting: 'Hello, Chain DB!' },
-//   { greeting: 'Hello' },
-//   { greeting: 'Hi there' },
-//   ...
-// ]
+// { greeting: 'Hello, Chain DB!' },
+// { greeting: 'Hello' },
+// { greeting: 'Hi there' },
+//  ...
 ```
 
 ### Real-time Events with WebSockets
@@ -140,14 +134,14 @@ import { EventTypes, EventData } from 'chain-db-ts'
 
 // 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)
+  console.log('Table updated:', eventData.table) // e.g. greetings
+  console.log('New data:', eventData.data) // e.g. { greeting: "Hello World!" }
 })
 
 // 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)
+  console.log('New data added to table:', eventData.table) // e.g. greetings
+  console.log('Data:', eventData.data) // e.g. { greeting: "Hello World!" }
 })
 
 // Unsubscribe from an event
@@ -176,7 +170,7 @@ The `EventData` object contains:
 
 ```typescript
 // Find items with exact matches
-const users = await userTable.findWhere(
+const users = await User.findWhere(
   { active: true, name: 'John' }, // criteria
   10, // limit (default: 1000)
   true // reverse order (default: true)
@@ -189,7 +183,7 @@ const users = await userTable.findWhere(
 import { Operators } from 'chain-db-ts'
 
 // Find items with advanced criteria
-const users = await userTable.findWhereAdvanced(
+const users = await User.findWhereAdvanced(
   [
     {
       field: 'name',
@@ -219,96 +213,6 @@ Available operators:
 - `STARTS_WITH` (for strings)
 - `ENDS_WITH` (for strings)
 
-### Other Table Methods
-
-```typescript
-// Check if a table is empty
-const isEmpty = greetingTable.isEmpty()
-
-// Get the table name
-const tableName = greetingTable.getName()
-
-// Refetch the table data from the database
-await greetingTable.refetch()
-```
-
-## Complete Example
-
-```typescript
-import { connect, EventTypes, EventData } from 'chain-db-ts'
-
-// 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