document-dataply 0.0.3-alpha.0 → 0.0.3-alpha.1

package/README.md

@@ -99,92 +99,32 @@ const ids = await db.insertBatch([
 
 ### Querying
 
-`document-dataply` supports various comparison operators.
+`document-dataply` supports powerful search capabilities based on B+Tree indexing.
 
 | Operator | Description |
 | :--- | :--- |
-| `lt` | Less than |
-| `lte` | Less than or equal to |
-| `gt` | Greater than |
-| `gte` | Greater than or equal to |
-| `equal` | Equal to |
-| `notEqual` | Not equal to |
-| `like` | SQL-style pattern matching (e.g., `Jo%`) |
-| `or` | If any value in the array is satisfied |
-
-Example of a complex query:
-```typescript
-const users = await db.select({
-  age: { gt: 18, lt: 65 },
-  'address.city': 'Seoul',
-  tags: { or: ['vip', 'premium'] }
-}).drain();
-```
+| `lt`, `lte`, `gt`, `gte` | Comparison operations |
+| `equal`, `notEqual` | Equality check |
+| `like` | Pattern matching |
+| `or` | Matching within an array |
 
-> [!IMPORTANT]
-> **Query Constraints**: Query conditions (`lt`, `gt`, `equal`, etc.) can only be used on fields explicitly indexed during initialization.
-> 
-> **If a field in the query is not indexed, that condition will be ignored.**
-> 
-> If you need to filter by unindexed fields, you should first retrieve the documents and then use JavaScript's native `.filter()` method.
-```typescript
-const results = await db.select({ /* indexed fields only */ }).drain();
-const filtered = results.filter(doc => doc.unindexedField === 'some-value');
-```
+For detailed operator usage, index constraints (including full scans), and sorting methods, see the [Query Guide (QUERY.md)](./docs/QUERY.md).
 
 ### Transactions
 
-To ensure the atomicity of multiple operations, use transactions.
+Ensure data integrity with ACID-compliant transactions. Use `commit()` and `rollback()` to process multiple operations atomically.
 
-```typescript
-const tx = db.createTransaction();
-try {
-  await db.insert({ name: 'Alice', age: 25 }, tx);
-  await db.insert({ name: 'Bob', age: 28 }, tx);
-  await tx.commit();
-} catch (error) {
-  await tx.rollback();
-  throw error;
-}
-```
+For detailed usage and error handling patterns, see the [Transaction Guide (TRANSACTION.md)](./docs/TRANSACTION.md).
 
 ### Updating and Deleting
 
-`document-dataply` provides flexible ways to update or delete documents matching a query. All these operations are performed in a memory-efficient streaming manner.
+`document-dataply` provides flexible ways to update or delete documents based on query results. All these operations are **Stream-based**, allowing you to handle millions of records without memory concerns.
 
-#### Partial Update
-Updates only specified fields of the matching documents.
+- **Partial Update**: Modify only specific fields or use a function for dynamic updates.
+- **Full Update**: Replace the entire document while preserving the original `_id`.
+- **Delete**: Permanently remove matching documents from both storage and indices.
 
-```typescript
-// Using an object to merge
-const count = await db.partialUpdate(
-  { name: 'John Doe' },
-  { status: 'active', updatedAt: Date.now() }
-);
-
-// Using a function for dynamic updates
-const count = await db.partialUpdate(
-  { age: { lt: 20 } },
-  (doc) => ({ age: doc.age + 1 })
-);
-```
-
-#### Full Update
-Completely replaces the documents matching the query, while preserving their original `_id`.
-
-```typescript
-const count = await db.fullUpdate(
-  { name: 'John Doe' },
-  { name: 'John Smith', age: 31, location: 'New York' }
-);
-```
-
-#### Delete
-Removes documents matching the query from both the index and storage.
-
-```typescript
-const deletedCount = await db.delete({ status: 'inactive' });
-```
+For details on streaming mechanisms and bandwidth optimization tips, see the [Stream Guide (STREAM.md)](./docs/STREAM.md).
 
 ## Tips and Advanced Features
 
@@ -206,13 +146,13 @@ Creates or opens a database instance. `T` defines the document structure.
 Initializes the database, sets up internal metadata, and prepares indices.
 
 ### `db.insert(document, tx?)`
-Inserts a single document. Returns the `_id` (`number`) of the document.
+Inserts a single document. Each document is automatically assigned a unique, immutable `_id` field. The method returns this `_id` (`number`).
 
 ### `db.insertBatch(documents, tx?)`
 Inserts multiple documents efficiently. Returns an array of `_ids` (`number[]`).
 
 ### `db.select(query, options?, tx?)`
-Searches for documents matching the query.
+Searches for documents matching the query. Passing an empty object (`{}`) as the `query` retrieves all documents.
 Returns an object `{ stream, drain }`.
 - `stream`: An async iterator to traverse results one by one.
 - `drain()`: A promise that resolves to an array of all matching documents.

package/dist/cjs/index.js

@@ -10022,8 +10022,8 @@ var DocumentDataply = class _DocumentDataply {
         throw new Error(`Query field "${field}" is not indexed. Available indexed fields: ${Array.from(this.indexedFields).join(", ")}`);
       }
     }
-    const orderBy = options.orderBy ?? "_id";
-    if (!this.indexedFields.has(orderBy)) {
+    const orderBy = options.orderBy;
+    if (orderBy !== void 0 && !this.indexedFields.has(orderBy)) {
       throw new Error(`orderBy field "${orderBy}" is not indexed. Available indexed fields: ${Array.from(this.indexedFields).join(", ")}`);
     }
     const {
@@ -10035,51 +10035,36 @@ var DocumentDataply = class _DocumentDataply {
       const isQueryEmpty = Object.keys(query).length === 0;
       const normalizedQuery = isQueryEmpty ? { _id: { gte: 0 } } : query;
       const verbose = self.verboseQuery(normalizedQuery);
-      const orderByTree = self.api.trees.get(orderBy);
       const selectivity = await self.getSelectivityCandidate(
         verbose,
-        orderByTree ? orderBy : void 0
+        orderBy
       );
       if (!selectivity) return;
       const { driver, others } = selectivity;
-      const isDriverOrderByField = orderByTree && driver.field === orderBy;
+      const isDriverOrderByField = orderBy === void 0 || driver.field === orderBy;
       if (isDriverOrderByField) {
-        const driverStream = driver.tree.whereStream(driver.condition, limit, sortOrder);
+        let keys = await driver.tree.keys(driver.condition, void 0, sortOrder);
+        for (const { tree, condition } of others) {
+          keys = await tree.keys(condition, keys, sortOrder);
+        }
         let i = 0;
-        for await (const [pk, val] of driverStream) {
+        for (const key of keys) {
           if (i >= limit) break;
-          let isMatch = true;
-          for (const { tree, condition } of others) {
-            const targetValue = await tree.get(pk);
-            if (targetValue === void 0 || !tree.verify(targetValue, condition)) {
-              isMatch = false;
-              break;
-            }
-          }
-          if (isMatch) {
-            const stringified = await self.api.select(pk, false, tx2);
-            if (!stringified) continue;
-            yield JSON.parse(stringified);
-            i++;
-          }
+          const stringified = await self.api.select(key, false, tx2);
+          if (!stringified) continue;
+          yield JSON.parse(stringified);
+          i++;
         }
       } else {
         const results = [];
-        const driverStream = driver.tree.whereStream(driver.condition);
-        for await (const [pk, val] of driverStream) {
-          let isMatch = true;
-          for (const { tree, condition } of others) {
-            const targetValue = await tree.get(pk);
-            if (targetValue === void 0 || !tree.verify(targetValue, condition)) {
-              isMatch = false;
-              break;
-            }
-          }
-          if (isMatch) {
-            const stringified = await self.api.select(pk, false, tx2);
-            if (!stringified) continue;
-            results.push(JSON.parse(stringified));
-          }
+        let keys = await driver.tree.keys(driver.condition, void 0);
+        for (const { tree, condition } of others) {
+          keys = await tree.keys(condition, keys);
+        }
+        for (const key of keys) {
+          const stringified = await self.api.select(key, false, tx2);
+          if (!stringified) continue;
+          results.push(JSON.parse(stringified));
         }
         results.sort((a, b) => {
           const aVal = a[orderBy] ?? a._id;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "document-dataply",
-  "version": "0.0.3-alpha.0",
+  "version": "0.0.3-alpha.1",
   "description": "Simple and powerful JSON document database supporting complex queries and flexible indexing policies.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",