document-dataply 0.0.2 → 0.0.3-alpha.0

package/README.md

@@ -33,14 +33,14 @@ type MyDocument = {
 }
 
 async function main() {
-  const db = new DocumentDataply<MyDocument>('my-database.db', {
+  const db = DocumentDataply.Define<MyDocument>().Options({
     wal: 'my-database.wal',
     indices: {
       name: true, // Index both existing and new data
       age: false, // Index only new data
       'tags.0': true // Index the first element of the 'tags' array
     }
-  });
+  }).Open('my-database.db');
 
   // Initialize database
   await db.init();
@@ -78,7 +78,7 @@ main();
 
 ### Indexing Policies
 
-When defining indices in the constructor, you can specify a boolean value.
+When defining indices in the `options`, you can specify a boolean value.
 
 - `true`: The library indexes all existing documents for that field during `init()`, and also indexes all subsequent insertions.
 - `false`: The library only indexes documents inserted after this configuration.
@@ -122,7 +122,7 @@ const users = await db.select({
 ```
 
 > [!IMPORTANT]
-> **Query Constraints**: Query conditions (`lt`, `gt`, `equal`, etc.) can only be used on fields explicitly indexed in the constructor.
+> **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.**
 > 
@@ -148,6 +148,44 @@ try {
 }
 ```
 
+### 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.
+
+#### Partial Update
+Updates only specified fields of the matching documents.
+
+```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' });
+```
+
 ## Tips and Advanced Features
 
 For more information on performance optimization and advanced features, see [TIPS.md](./docs/TIPS.md).
@@ -160,9 +198,9 @@ For more information on performance optimization and advanced features, see [TIP
 
 ## API Reference
 
-### `new DocumentDataply<T>(file, options)`
-Creates a new database instance. `T` defines the document structure.
-`options.indices` is an object where keys are field names and values are booleans indicating whether to index.
+### `DocumentDataply.Define<T>().Options(options).Open(file)`
+Creates or opens a database instance. `T` defines the document structure.
+`options.indices` is an object where keys are field names and values are booleans indicating the [Indexing Policy](#indexing-policies).
 
 ### `db.init()`
 Initializes the database, sets up internal metadata, and prepares indices.
@@ -179,6 +217,15 @@ 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.
 
+### `db.partialUpdate(query, newFields, tx?)`
+Partially updates documents matching the query. `newFields` can be a partial object or a function that returns a partial object. Returns the number of updated documents.
+
+### `db.fullUpdate(query, newDocument, tx?)`
+Fully replaces documents matching the query while preserving their `_id`. Returns the number of updated documents.
+
+### `db.delete(query, tx?)`
+Deletes documents matching the query. Returns the number of deleted documents.
+
 ### `db.getMetadata(tx?)`
 Returns physical storage information (number of pages, number of rows, etc.).
 

package/dist/cjs/index.js

@@ -9683,7 +9683,40 @@ var DocumentDataplyAPI = class extends import_dataply3.DataplyAPI {
     await this.update(1, JSON.stringify(metadata), tx);
   }
 };
-var DocumentDataply = class {
+var DocumentDataply = class _DocumentDataply {
+  /**
+   * Starts the database definition by setting the document type.
+   * This is used to ensure TypeScript type inference works correctly for the document structure.
+   * @template T The structure of the document to be stored.
+   */
+  static Define() {
+    return {
+      /**
+       * Sets the options for the database, such as index configurations and WAL settings.
+       * @template IC The configuration of indices.
+       * @param options The database initialization options.
+       */
+      Options: (options) => _DocumentDataply.Options(options)
+    };
+  }
+  /**
+   * Internal method used by the Define-chain to pass options.
+   */
+  static Options(options) {
+    return {
+      /**
+       * Creates or opens the database instance with the specified file path.
+       * @param file The path to the database file.
+       */
+      Open: (file) => _DocumentDataply.Open(file, options)
+    };
+  }
+  /**
+   * Internal method used to finalize construction and create the instance.
+   */
+  static Open(file, options) {
+    return new _DocumentDataply(file, options);
+  }
   api;
   indexedFields;
   operatorConverters = {
@@ -9869,6 +9902,112 @@ var DocumentDataply = class {
       return ids;
     }, tx));
   }
+  /**
+   * Internal update method used by both fullUpdate and partialUpdate
+   * @param query The query to use
+   * @param computeUpdatedDoc Function that computes the updated document from the original
+   * @param tx The transaction to use
+   * @returns The number of updated documents
+   */
+  async updateInternal(query, computeUpdatedDoc, tx) {
+    const idTree = this.api.trees.get("_id");
+    if (!idTree) {
+      throw new Error("ID tree not found");
+    }
+    const { stream } = this.select(query, {}, tx);
+    let updatedCount = 0;
+    for await (const doc of stream) {
+      const id = doc._id;
+      let pk = null;
+      for await (const [entryPk] of idTree.whereStream({ primaryEqual: { v: id } })) {
+        pk = entryPk;
+        break;
+      }
+      if (pk === null) continue;
+      const updatedDoc = computeUpdatedDoc(doc);
+      const oldFlatDoc = this.api.flattenDocument(doc);
+      const newFlatDoc = this.api.flattenDocument(updatedDoc);
+      for (const [field, tree] of this.api.trees) {
+        const oldV = oldFlatDoc[field];
+        const newV = newFlatDoc[field];
+        if (oldV === newV) continue;
+        if (oldV !== void 0) {
+          await tree.delete(pk, { k: pk, v: oldV });
+        }
+        if (newV !== void 0) {
+          await tree.insert(pk, { k: pk, v: newV });
+        }
+      }
+      await this.api.update(pk, JSON.stringify(updatedDoc), tx);
+      updatedCount++;
+    }
+    return updatedCount;
+  }
+  /**
+   * Fully update documents from the database that match the query
+   * @param query The query to use (only indexed fields + _id allowed)
+   * @param newRecord Complete document to replace with, or function that receives current document and returns new document
+   * @param tx The transaction to use
+   * @returns The number of updated documents
+   */
+  async fullUpdate(query, newRecord, tx) {
+    return this.api.writeLock(() => this.api.runWithDefault(async (tx2) => {
+      return this.updateInternal(query, (doc) => {
+        const newDoc = typeof newRecord === "function" ? newRecord(doc) : newRecord;
+        return { _id: doc._id, ...newDoc };
+      }, tx2);
+    }, tx));
+  }
+  /**
+   * Partially update documents from the database that match the query
+   * @param query The query to use (only indexed fields + _id allowed)
+   * @param newRecord Partial document to merge, or function that receives current document and returns partial update
+   * @param tx The transaction to use
+   * @returns The number of updated documents
+   */
+  async partialUpdate(query, newRecord, tx) {
+    return this.api.writeLock(() => this.api.runWithDefault(async (tx2) => {
+      return this.updateInternal(query, (doc) => {
+        const partialUpdate = typeof newRecord === "function" ? newRecord(doc) : newRecord;
+        delete partialUpdate._id;
+        return { ...doc, ...partialUpdate };
+      }, tx2);
+    }, tx));
+  }
+  /**
+   * Delete documents from the database that match the query
+   * @param query The query to use (only indexed fields + _id allowed)
+   * @param tx The transaction to use
+   * @returns The number of deleted documents
+   */
+  async delete(query, tx) {
+    return this.api.writeLock(() => this.api.runWithDefault(async (tx2) => {
+      const idTree = this.api.trees.get("_id");
+      if (!idTree) {
+        throw new Error("ID tree not found");
+      }
+      const { stream } = this.select(query, {}, tx2);
+      let deletedCount = 0;
+      for await (const doc of stream) {
+        const id = doc._id;
+        let pk = null;
+        for await (const [entryPk] of idTree.whereStream({ primaryEqual: { v: id } })) {
+          pk = entryPk;
+          break;
+        }
+        if (pk === null) continue;
+        const flatDoc = this.api.flattenDocument(doc);
+        for (const [field, tree] of this.api.trees) {
+          const v = flatDoc[field];
+          if (v === void 0) continue;
+          await tree.delete(pk, { k: pk, v });
+        }
+        await this.api.delete(pk, true, tx2);
+        deletedCount++;
+      }
+      return deletedCount;
+    }, tx));
+  }
   /**
    * Select documents from the database
    * @param query The query to use (only indexed fields + _id allowed)

package/dist/types/core/bptree/documentStrategy.d.ts

@@ -2,10 +2,10 @@ import type { DataplyTreeValue, Primitive } from '../../types';
 import { BPTreeNode, SerializeStrategyAsync, type SerializeStrategyHead } from 'dataply';
 import { DocumentDataplyAPI } from '../document';
 export declare class DocumentSerializeStrategyAsync<T extends Primitive> extends SerializeStrategyAsync<number, DataplyTreeValue<T>> {
-    protected readonly api: DocumentDataplyAPI<any>;
-    protected readonly txContext: DocumentDataplyAPI<any>['txContext'];
+    protected readonly api: DocumentDataplyAPI<any, any>;
+    protected readonly txContext: DocumentDataplyAPI<any, any>['txContext'];
     readonly treeKey: string;
-    constructor(order: number, api: DocumentDataplyAPI<any>, txContext: DocumentDataplyAPI<any>['txContext'], treeKey: string);
+    constructor(order: number, api: DocumentDataplyAPI<any, any>, txContext: DocumentDataplyAPI<any, any>['txContext'], treeKey: string);
     id(isLeaf: boolean): Promise<string>;
     read(id: string): Promise<BPTreeNode<number, DataplyTreeValue<T>>>;
     write(id: string, node: BPTreeNode<number, DataplyTreeValue<T>>): Promise<void>;

package/dist/types/core/document.d.ts

@@ -1,7 +1,7 @@
-import type { DataplyTreeValue, DocumentDataplyInnerMetadata, DocumentDataplyOptions, DocumentJSON, FlattenedDocumentJSON, Primitive, DocumentDataplyQuery, FinalFlatten, DocumentDataplyCondition, DataplyDocument, DocumentDataplyMetadata, DocumentDataplyQueryOptions, IndexedDocumentDataplyQuery } from '../types';
+import type { DataplyTreeValue, DocumentDataplyInnerMetadata, DocumentDataplyOptions, DocumentJSON, FlattenedDocumentJSON, Primitive, DocumentDataplyQuery, DocumentDataplyIndexedQuery, DocumentDataplyCondition, DataplyDocument, DocumentDataplyMetadata, DocumentDataplyQueryOptions, IndexConfig } from '../types';
 import { DataplyAPI, Transaction, BPTreeAsync } from 'dataply';
 import { DocumentValueComparator } from './bptree/documentComparator';
-export declare class DocumentDataplyAPI<T extends DocumentJSON> extends DataplyAPI {
+export declare class DocumentDataplyAPI<T extends DocumentJSON, IC extends IndexConfig<T>> extends DataplyAPI {
     runWithDefault: <T_1>(callback: (tx: Transaction) => Promise<T_1>, tx?: Transaction) => Promise<T_1>;
     streamWithDefault: <T_1>(callback: (tx: Transaction) => AsyncGenerator<T_1>, tx?: Transaction) => AsyncGenerator<T_1>;
     indices: DocumentDataplyInnerMetadata['indices'];
@@ -9,7 +9,7 @@ export declare class DocumentDataplyAPI<T extends DocumentJSON> extends DataplyA
     readonly comparator: DocumentValueComparator<DataplyTreeValue<Primitive>, Primitive>;
     private pendingBackfillFields;
     private readonly lock;
-    constructor(file: string, options: DocumentDataplyOptions<T>);
+    constructor(file: string, options: DocumentDataplyOptions<T, IC>);
     readLock<T>(fn: () => T): Promise<T>;
     writeLock<T>(fn: () => T): Promise<T>;
     getDocument(pk: number, tx?: Transaction): Promise<DataplyDocument<T>>;
@@ -34,11 +34,38 @@ export declare class DocumentDataplyAPI<T extends DocumentJSON> extends DataplyA
     getDocumentInnerMetadata(tx: Transaction): Promise<DocumentDataplyInnerMetadata>;
     updateDocumentInnerMetadata(metadata: DocumentDataplyInnerMetadata, tx: Transaction): Promise<void>;
 }
-export declare class DocumentDataply<T extends DocumentJSON, I extends string = keyof FinalFlatten<T> & string> {
-    protected readonly api: DocumentDataplyAPI<T>;
+export declare class DocumentDataply<T extends DocumentJSON, IC extends IndexConfig<T>> {
+    /**
+     * Starts the database definition by setting the document type.
+     * This is used to ensure TypeScript type inference works correctly for the document structure.
+     * @template T The structure of the document to be stored.
+     */
+    static Define<T extends DocumentJSON>(): {
+        /**
+         * Sets the options for the database, such as index configurations and WAL settings.
+         * @template IC The configuration of indices.
+         * @param options The database initialization options.
+         */
+        Options: <IC extends IndexConfig<T>>(options: DocumentDataplyOptions<T, IC>) => {
+            /**
+             * Creates or opens the database instance with the specified file path.
+             * @param file The path to the database file.
+             */
+            Open: (file: string) => DocumentDataply<T, IC>;
+        };
+    };
+    /**
+     * Internal method used by the Define-chain to pass options.
+     */
+    private static Options;
+    /**
+     * Internal method used to finalize construction and create the instance.
+     */
+    private static Open;
+    protected readonly api: DocumentDataplyAPI<T, IC>;
     private readonly indexedFields;
     private readonly operatorConverters;
-    constructor(file: string, options?: DocumentDataplyOptions<T>);
+    protected constructor(file: string, options?: DocumentDataplyOptions<T, IC>);
     /**
      * Initialize the document database
      */
@@ -58,7 +85,7 @@ export declare class DocumentDataply<T extends DocumentJSON, I extends string =
      * @param orderByField Optional field name for orderBy optimization
      * @returns Driver and other candidates for query execution
      */
-    getSelectivityCandidate<U extends Partial<IndexedDocumentDataplyQuery<FinalFlatten<DataplyDocument<T>>, I>>, V extends DataplyTreeValue<U>>(query: Partial<DocumentDataplyQuery<V>>, orderByField?: string): Promise<{
+    getSelectivityCandidate<U extends Partial<DocumentDataplyIndexedQuery<T, IC>>, V extends DataplyTreeValue<U>>(query: Partial<DocumentDataplyQuery<V>>, orderByField?: string): Promise<{
         driver: {
             tree: BPTreeAsync<number, V>;
             condition: Partial<DocumentDataplyCondition<U>>;
@@ -85,6 +112,37 @@ export declare class DocumentDataply<T extends DocumentJSON, I extends string =
      * @returns The primary keys of the inserted documents
      */
     insertBatch(documents: T[], tx?: Transaction): Promise<number[]>;
+    /**
+     * Internal update method used by both fullUpdate and partialUpdate
+     * @param query The query to use
+     * @param computeUpdatedDoc Function that computes the updated document from the original
+     * @param tx The transaction to use
+     * @returns The number of updated documents
+     */
+    private updateInternal;
+    /**
+     * Fully update documents from the database that match the query
+     * @param query The query to use (only indexed fields + _id allowed)
+     * @param newRecord Complete document to replace with, or function that receives current document and returns new document
+     * @param tx The transaction to use
+     * @returns The number of updated documents
+     */
+    fullUpdate(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, newRecord: T | ((document: DataplyDocument<T>) => T), tx?: Transaction): Promise<number>;
+    /**
+     * Partially update documents from the database that match the query
+     * @param query The query to use (only indexed fields + _id allowed)
+     * @param newRecord Partial document to merge, or function that receives current document and returns partial update
+     * @param tx The transaction to use
+     * @returns The number of updated documents
+     */
+    partialUpdate(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, newRecord: Partial<DataplyDocument<T>> | ((document: DataplyDocument<T>) => Partial<DataplyDocument<T>>), tx?: Transaction): Promise<number>;
+    /**
+     * Delete documents from the database that match the query
+     * @param query The query to use (only indexed fields + _id allowed)
+     * @param tx The transaction to use
+     * @returns The number of deleted documents
+     */
+    delete(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, tx?: Transaction): Promise<number>;
     /**
      * Select documents from the database
      * @param query The query to use (only indexed fields + _id allowed)
@@ -93,7 +151,7 @@ export declare class DocumentDataply<T extends DocumentJSON, I extends string =
      * @returns The documents that match the query
      * @throws Error if query or orderBy contains non-indexed fields
      */
-    select(query: Partial<IndexedDocumentDataplyQuery<FinalFlatten<DataplyDocument<T>>, I>>, options?: DocumentDataplyQueryOptions<FinalFlatten<DataplyDocument<T>>, I>, tx?: Transaction): {
+    select(query: Partial<DocumentDataplyIndexedQuery<T, IC>>, options?: DocumentDataplyQueryOptions<T, IC>, tx?: Transaction): {
         stream: AsyncIterableIterator<DataplyDocument<T>>;
         drain: () => Promise<DataplyDocument<T>[]>;
     };

package/dist/types/types/index.d.ts

@@ -47,26 +47,26 @@ export type DocumentDataplyCondition<V> = {
     or?: Partial<V>[];
     like?: string;
 };
-export type DocumentDataplyQueryOptions<V, I extends string = string> = {
-    limit?: number;
-    orderBy?: I | '_id';
-    sortOrder?: BPTreeOrder;
-};
 export type DocumentDataplyQuery<T> = {
     [key in keyof T]?: T[key] | DocumentDataplyCondition<T[key]>;
 } & {
     [key: string]: any;
 };
 /**
- * Query type restricted to indexed fields only (+ _id)
+ * Query type restricted to indexed fields only
  */
-export type IndexedDocumentDataplyQuery<T, I extends string> = {
-    [key in (I | '_id')]?: key extends keyof T ? T[key] | DocumentDataplyCondition<T[key]> : never;
+export type DocumentDataplyIndexedQuery<T extends DocumentJSON, IC extends IndexConfig<T>> = {
+    [key in keyof IC]: key extends keyof FinalFlatten<DataplyDocument<T>> ? FinalFlatten<DataplyDocument<T>>[key] | DocumentDataplyCondition<FinalFlatten<DataplyDocument<T>>[key]> : never;
 };
 export interface DataplyTreeValue<T> {
     k: number;
     v: T;
 }
+export type DocumentDataplyQueryOptions<T extends DocumentJSON, IC extends IndexConfig<T>> = {
+    limit?: number;
+    orderBy?: ExtractIndexKeys<T, IC> | '_id';
+    sortOrder?: BPTreeOrder;
+};
 /**
  * T가 객체인지 확인하고, 객체라면 하위 키를 재귀적으로 탐색합니다.
  */
@@ -75,7 +75,7 @@ type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17
  * T가 객체인지 확인하고, 객체라면 하위 키를 재귀적으로 탐색합니다.
  * Depth 제한을 두어 "Type instantiation is excessively deep and possibly infinite" 에러를 방지합니다.
  */
-export type DeepFlattenKeys<T, Prefix extends string = "", D extends number = 12> = [
+export type DeepFlattenKeys<T, Prefix extends string = "", D extends number = 5> = [
     D
 ] extends [0] ? never : T extends Primitive ? (Prefix extends `${infer P}.` ? P : never) : T extends readonly any[] ? (DeepFlattenKeys<T[number], `${Prefix}${number}.`, Prev[D]>) : T extends object ? {
     [K in keyof T & string]: NonNullable<T[K]> extends Primitive ? `${Prefix}${K}` : DeepFlattenKeys<NonNullable<T[K]>, `${Prefix}${K}.`, Prev[D]>;
@@ -88,15 +88,26 @@ type GetTypeByPath<T, Path extends string> = T extends readonly (infer U)[] ? Pa
 export type FinalFlatten<T> = {
     [P in DeepFlattenKeys<T>]: GetTypeByPath<T, P & string>;
 };
-export interface DocumentDataplyOptions<T> extends DataplyOptions {
+export type DocumentDataplyIndices<T extends DocumentJSON, IC extends IndexConfig<T>> = {
+    [key in keyof IC & keyof FinalFlatten<T>]: GetTypeByPath<T, key>;
+};
+/**
+ * Index configuration type - keys are field names, values are boolean
+ */
+export type IndexConfig<T> = Partial<{
+    [key in keyof FinalFlatten<T>]: boolean;
+}>;
+/**
+ * Extract index keys from IndexConfig
+ */
+export type ExtractIndexKeys<T extends DocumentJSON, IC extends IndexConfig<T>> = keyof IC & keyof FinalFlatten<DataplyDocument<T>> & string;
+export interface DocumentDataplyOptions<T, IC extends IndexConfig<T> = IndexConfig<T>> extends DataplyOptions {
     /**
-     * Indecies to create when initializing the database.
-     * If not specified, no indecies will be created.
+     * Indices to create when initializing the database.
+     * If not specified, no indices will be created.
      * If the value of the index is `true`, the index will be created for the already inserted data.
      * If the value of the index is `false`, the index will not be created for the already inserted data.
      */
-    indices?: Partial<{
-        [key in keyof FinalFlatten<T>]: boolean;
-    }>;
+    indices?: IC;
 }
 export {};

package/package.json

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