document-dataply 0.0.2-alpha.2 → 0.0.2

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

@@ -4,7 +4,7 @@ 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 treeKey: string;
+    readonly treeKey: string;
     constructor(order: number, api: DocumentDataplyAPI<any>, txContext: DocumentDataplyAPI<any>['txContext'], treeKey: string);
     id(isLeaf: boolean): Promise<string>;
     read(id: string): Promise<BPTreeNode<number, DataplyTreeValue<T>>>;

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

@@ -1,14 +1,27 @@
-import type { DataplyTreeValue, DocumentDataplyInnerMetadata, DocumentDataplyOptions, DocumentJSON, FlattenedDocumentJSON, Primitive, DocumentDataplyQuery, FinalFlatten, DocumentDataplyCondition, DataplyDocument, DocumentDataplyMetadata } from '../types';
+import type { DataplyTreeValue, DocumentDataplyInnerMetadata, DocumentDataplyOptions, DocumentJSON, FlattenedDocumentJSON, Primitive, DocumentDataplyQuery, FinalFlatten, DocumentDataplyCondition, DataplyDocument, DocumentDataplyMetadata, DocumentDataplyQueryOptions, IndexedDocumentDataplyQuery } from '../types';
 import { DataplyAPI, Transaction, BPTreeAsync } from 'dataply';
 import { DocumentValueComparator } from './bptree/documentComparator';
 export declare class DocumentDataplyAPI<T extends DocumentJSON> extends DataplyAPI {
     runWithDefault: <T_1>(callback: (tx: Transaction) => Promise<T_1>, tx?: Transaction) => Promise<T_1>;
-    treeHeads: DocumentDataplyInnerMetadata['treeHeads'];
+    streamWithDefault: <T_1>(callback: (tx: Transaction) => AsyncGenerator<T_1>, tx?: Transaction) => AsyncGenerator<T_1>;
+    indices: DocumentDataplyInnerMetadata['indices'];
     readonly trees: Map<string, BPTreeAsync<number, DataplyTreeValue<Primitive>>>;
     readonly comparator: DocumentValueComparator<DataplyTreeValue<Primitive>, Primitive>;
-    constructor(file: string, options: DocumentDataplyOptions);
-    ensureTree<T extends Primitive>(field: string): Promise<BPTreeAsync<number, DataplyTreeValue<T>>>;
-    createDocumentMetadata(): DocumentDataplyInnerMetadata;
+    private pendingBackfillFields;
+    private readonly lock;
+    constructor(file: string, options: DocumentDataplyOptions<T>);
+    readLock<T>(fn: () => T): Promise<T>;
+    writeLock<T>(fn: () => T): Promise<T>;
+    getDocument(pk: number, tx?: Transaction): Promise<DataplyDocument<T>>;
+    /**
+     * Backfill indices for fields that were added with `true` option after data was inserted.
+     * This method should be called after `init()` if you want to index existing documents
+     * for newly added index fields.
+     *
+     * @returns Number of documents that were backfilled
+     */
+    backfillIndices(tx?: Transaction): Promise<number>;
+    createDocumentInnerMetadata(indices: DocumentDataplyInnerMetadata['indices']): DocumentDataplyInnerMetadata;
     initializeDocumentFile(tx: Transaction): Promise<void>;
     verifyDocumentFile(tx: Transaction): Promise<boolean>;
     /**
@@ -20,12 +33,12 @@ export declare class DocumentDataplyAPI<T extends DocumentJSON> extends DataplyA
     getDocumentMetadata(tx: Transaction): Promise<DocumentDataplyMetadata>;
     getDocumentInnerMetadata(tx: Transaction): Promise<DocumentDataplyInnerMetadata>;
     updateDocumentInnerMetadata(metadata: DocumentDataplyInnerMetadata, tx: Transaction): Promise<void>;
-    updateTreeHead(tx: Transaction): Promise<void>;
 }
-export declare class DocumentDataply<T extends DocumentJSON> {
+export declare class DocumentDataply<T extends DocumentJSON, I extends string = keyof FinalFlatten<T> & string> {
     protected readonly api: DocumentDataplyAPI<T>;
+    private readonly indexedFields;
     private readonly operatorConverters;
-    constructor(file: string, options?: DocumentDataplyOptions);
+    constructor(file: string, options?: DocumentDataplyOptions<T>);
     /**
      * Initialize the document database
      */
@@ -41,17 +54,20 @@ export declare class DocumentDataply<T extends DocumentJSON> {
     private verboseQuery;
     /**
      * Get the selectivity candidate for the given query
-     * @param query
-     * @returns
+     * @param query The query conditions
+     * @param orderByField Optional field name for orderBy optimization
+     * @returns Driver and other candidates for query execution
      */
-    getSelectivityCandidate<U extends FinalFlatten<DataplyDocument<T>>, V extends DataplyTreeValue<U>>(query: Partial<DocumentDataplyQuery<V>>): Promise<{
+    getSelectivityCandidate<U extends Partial<IndexedDocumentDataplyQuery<FinalFlatten<DataplyDocument<T>>, I>>, V extends DataplyTreeValue<U>>(query: Partial<DocumentDataplyQuery<V>>, orderByField?: string): Promise<{
         driver: {
             tree: BPTreeAsync<number, V>;
             condition: Partial<DocumentDataplyCondition<U>>;
+            field: string;
         };
         others: {
             tree: BPTreeAsync<number, V>;
             condition: Partial<DocumentDataplyCondition<U>>;
+            field: string;
         }[];
     } | null>;
     private insertDocument;
@@ -59,17 +75,28 @@ export declare class DocumentDataply<T extends DocumentJSON> {
      * Insert a document into the database
      * @param document The document to insert
      * @param tx The transaction to use
-     * @returns True if the document was inserted successfully
+     * @returns The primary key of the inserted document
+     */
+    insert(document: T, tx?: Transaction): Promise<number>;
+    /**
+     * Insert a batch of documents into the database
+     * @param documents The documents to insert
+     * @param tx The transaction to use
+     * @returns The primary keys of the inserted documents
      */
-    insert(document: T, tx?: Transaction): Promise<boolean>;
+    insertBatch(documents: T[], tx?: Transaction): Promise<number[]>;
     /**
      * Select documents from the database
-     * @param query The query to use
-     * @param limit The maximum number of documents to return
+     * @param query The query to use (only indexed fields + _id allowed)
+     * @param options The options to use
      * @param tx The transaction to use
      * @returns The documents that match the query
+     * @throws Error if query or orderBy contains non-indexed fields
      */
-    select(query: Partial<DocumentDataplyQuery<FinalFlatten<DataplyDocument<T>>>>, limit?: number, tx?: Transaction): Promise<DataplyDocument<T>[]>;
+    select(query: Partial<IndexedDocumentDataplyQuery<FinalFlatten<DataplyDocument<T>>, I>>, options?: DocumentDataplyQueryOptions<FinalFlatten<DataplyDocument<T>>, I>, tx?: Transaction): {
+        stream: AsyncIterableIterator<DataplyDocument<T>>;
+        drain: () => Promise<DataplyDocument<T>[]>;
+    };
     /**
      * Close the document database
      */

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

@@ -1,4 +1,4 @@
-import type { DataplyOptions, SerializeStrategyHead } from 'dataply';
+import type { BPTreeOrder, DataplyOptions } from 'dataply';
 export type Primitive = string | number | boolean | null;
 export type JSONValue = Primitive | JSONValue[] | {
     [key: string]: JSONValue;
@@ -15,7 +15,9 @@ export interface DocumentDataplyInnerMetadata {
     createdAt: number;
     updatedAt: number;
     lastId: number;
-    treeHeads: Record<string, SerializeStrategyHead>;
+    indices: {
+        [key: string]: [number, boolean];
+    };
 }
 export interface DocumentDataplyMetadata {
     /**
@@ -42,14 +44,25 @@ export type DocumentDataplyCondition<V> = {
     gte?: Partial<V>;
     equal?: Partial<V>;
     notEqual?: Partial<V>;
-    like?: Partial<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)
+ */
+export type IndexedDocumentDataplyQuery<T, I extends string> = {
+    [key in (I | '_id')]?: key extends keyof T ? T[key] | DocumentDataplyCondition<T[key]> : never;
+};
 export interface DataplyTreeValue<T> {
     k: number;
     v: T;
@@ -64,8 +77,8 @@ type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17
  */
 export type DeepFlattenKeys<T, Prefix extends string = "", D extends number = 12> = [
     D
-] extends [0] ? never : T extends Primitive ? (Prefix extends `${infer P}.` ? P : never) : T extends readonly any[] ? ((Prefix extends `${infer P}.` ? P : never) | DeepFlattenKeys<T[number], `${Prefix}${number}.`, Prev[D]>) : T extends object ? {
-    [K in keyof T & string]: NonNullable<T[K]> extends Primitive ? `${Prefix}${K}` : `${Prefix}${K}` | DeepFlattenKeys<NonNullable<T[K]>, `${Prefix}${K}.`, Prev[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]>;
 }[keyof T & string] : never;
 /**
  * 경로 문자열(Path)을 기반으로 원본 객체(T)에서 타입을 찾아옵니다.
@@ -75,6 +88,15 @@ 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 extends DataplyOptions {
+export interface DocumentDataplyOptions<T> extends DataplyOptions {
+    /**
+     * Indecies to create when initializing the database.
+     * If not specified, no indecies 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;
+    }>;
 }
 export {};

package/dist/types/utils/catchPromise.d.ts

@@ -0,0 +1,12 @@
+type CatchPromiseSuccess<T> = [undefined, T];
+type CatchPromiseError = [Error];
+type CatchPromiseResult<T> = CatchPromiseSuccess<T> | CatchPromiseError;
+/**
+ * Catches a promise and returns a tuple of [error, result]
+ * If the promise is resolved, the first element of the tuple is `undefined`
+ * If the promise is rejected, the first element of the tuple is the `error`
+ * @param promise Promise to catch
+ * @returns Tuple of [error, result]
+ */
+export declare function catchPromise<T>(promise: Promise<T>): Promise<CatchPromiseResult<T>>;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "document-dataply",
-  "version": "0.0.2-alpha.2",
-  "description": "",
+  "version": "0.0.2",
+  "description": "Simple and powerful JSON document database supporting complex queries and flexible indexing policies.",
   "license": "MIT",
   "author": "izure <admin@izure.org>",
   "type": "commonjs",
@@ -25,8 +25,21 @@
     "test": "jest -i",
     "build": "node build/index.js && tsc"
   },
+  "keywords": [
+    "database",
+    "document-database",
+    "nosql",
+    "json",
+    "indexing",
+    "bptree",
+    "transactions",
+    "acid",
+    "embedded-database",
+    "deep-indexing",
+    "dataply"
+  ],
   "dependencies": {
-    "dataply": "^0.0.16-alpha.0"
+    "dataply": "^0.0.18"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",