@wxn0brp/db-core 0.11.0 → 0.11.1-alpha.1

package/README.md

@@ -1,17 +1,30 @@
 # @wxn0brp/db-core
 
-Core library for [ValtheraDB](https://github.com/wxn0brp/ValtheraDB).
+Core runtime for [ValtheraDB](https://github.com/wxn0brP/ValtheraDB). This package contains the shared database logic that the higher-level Valthera packages build on.
 
-## ⚠️ Disclaimer
+It is usually not something you install directly unless you are:
 
-It is **not recommended** to install this module separately unless you plan to create your own ValtheraDB adapter.
+- building a custom storage adapter
+- extending the lower-level database runtime
+- working on Valthera itself
 
-## Installation
+## Install
 
 ```bash
 npm install @wxn0brp/db-core
 ```
 
+## What It Provides
+
+- collection and document primitives
+- query and update operators
+- relation handling
+- shared types used by the Valthera packages
+
+## Package Note
+
+If you are building an application, you probably want `@wxn0brp/db` instead of this package. `db-core` is the internal foundation.
+
 ## Documentation
 
 See [typedoc](https://wxn0brp.github.io/ValtheraDB-core/).
@@ -22,4 +35,4 @@ Contributions are welcome! Please submit pull requests or open issues on GitHub.
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+MIT. See [LICENSE](LICENSE).

package/dist/db/valthera.d.ts

@@ -13,11 +13,30 @@ import { ValtheraCompatible } from "../types/valthera.js";
 export declare class ValtheraClass implements ValtheraCompatible {
     dbAction: ActionsBase;
     executor: ExecutorInterface;
-    emiter: VEE<{
+    emitter: VEE<{
         [K in keyof ValtheraCompatible]: (query: VQuery, result: Awaited<ReturnType<ValtheraCompatible[K]>>) => void;
     } & {
         "*": (name: keyof ValtheraCompatible, query: VQuery, result: any) => void;
     }>;
+    /** @deprecated typo */
+    emiter: VEE<{
+        c: (query: VQuery, result: Collection<unknown>) => void;
+        getCollections: (query: VQuery, result: string[]) => void;
+        ensureCollection: (query: VQuery, result: boolean) => void;
+        issetCollection: (query: VQuery, result: boolean) => void;
+        add: (query: VQuery, result: unknown) => void;
+        find: (query: VQuery, result: unknown[]) => void;
+        findOne: (query: VQuery, result: unknown) => void;
+        update: (query: VQuery, result: unknown[]) => void;
+        updateOne: (query: VQuery, result: unknown) => void;
+        remove: (query: VQuery, result: unknown[]) => void;
+        removeOne: (query: VQuery, result: unknown) => void;
+        removeCollection: (query: VQuery, result: boolean) => void;
+        updateOneOrAdd: (query: VQuery, result: VQueryT.UpdateOneOrAddResult<unknown>) => void;
+        toggleOne: (query: VQuery, result: VQueryT.ToggleOneResult<unknown>) => void;
+    } & {
+        "*": (name: keyof ValtheraCompatible, query: VQuery, result: any) => void;
+    }>;
     version: string;
     constructor(options: DbOpts);
     init(...args: any[]): Promise<any>;

package/dist/db/valthera.js

@@ -9,7 +9,9 @@ import { version } from "../version.js";
 export class ValtheraClass {
     dbAction;
     executor;
-    emiter = new VEE();
+    emitter = new VEE();
+    /** @deprecated typo */
+    emiter = this.emitter;
     version = version;
     constructor(options) {
         this.dbAction = options.dbAction;
@@ -31,7 +33,7 @@ export class ValtheraClass {
     async execute(name, query) {
         await this.init();
         const result = await this.executor.addOp(this.dbAction[name].bind(this.dbAction), query, typeof query === "string" ? query : query.collection);
-        this.emiter.emit(name, query, result);
+        this.emitter.emit(name, query, result);
         return result;
     }
     /**

package/dist/types/arg.d.ts

@@ -7,5 +7,5 @@ export type Arg<T = any> = {
 } & Record<string, any>;
 export type SearchFunc<T = any> = (data: T, context: VContext) => boolean;
 export type UpdaterFunc<T = any> = (data: T, context: VContext) => Data | void;
-export type Search<T = any> = SearchOptions<T> | SearchFunc<T>;
-export type Updater<T = any> = UpdaterArg<T> | UpdaterFunc<T>;
+export type Search<T = any, AllowFn extends boolean = true> = AllowFn extends true ? SearchOptions<T> | SearchFunc<T> : SearchOptions<T>;
+export type Updater<T = any, AllowFn extends boolean = true> = AllowFn extends true ? UpdaterArg<T> | UpdaterFunc<T> : UpdaterArg<T>;

package/dist/types/fileCpu.d.ts

@@ -5,27 +5,27 @@ export interface FileCpu {
      * Asynchronously adds an entry to a file.
      * @returns A promise resolving to `void`.
      */
-    add(file: string, config: VQueryT.Add): Promise<void>;
+    add(file: string, config: VQueryT.Add, opts?: any): Promise<void>;
     /**
      * Asynchronously finds multiple entries in a file based on search criteria.
      * @returns A promise resolving to an array of found entries, or `false` if the file does not exist.
      */
-    find(file: string, config: VQueryT.Find): Promise<DataInternal[]>;
+    find(file: string, config: VQueryT.Find, opts?: any): Promise<DataInternal[]>;
     /**
      * Asynchronously finds one entry in a file based on search criteria.
      * @returns A promise resolving to the found entry or `false` if not found.
      */
-    findOne(file: string, config: VQueryT.FindOne): Promise<DataInternal | false>;
+    findOne(file: string, config: VQueryT.FindOne, opts?: any): Promise<DataInternal | false>;
     /**
    * Asynchronously removes entries from a file based on search criteria.
    * @param one If `true`, removes only the first matching entry.
    * @returns A promise resolving to `true` if at least one entry was removed, otherwise `false`.
    */
-    remove(file: string, config: VQueryT.Remove, one: boolean): Promise<DataInternal[]>;
+    remove(file: string, config: VQueryT.Remove, one: boolean, opts?: any): Promise<DataInternal[]>;
     /**
      * Asynchronously updates entries in a file based on search criteria and an updater function or object.
      * @param one If `true`, updates only the first matching entry.
      * @returns A promise resolving to `true` if at least one entry was updated, otherwise `false`.
      */
-    update(file: string, config: VQueryT.Update, one: boolean): Promise<DataInternal[]>;
+    update(file: string, config: VQueryT.Update, one: boolean, opts?: any): Promise<DataInternal[]>;
 }

package/dist/types/query.d.ts

@@ -13,28 +13,60 @@ import { VContext } from "./types.js";
  */
 export interface VQuery_Control {
 }
-export interface VQuery<T = Data> {
+export interface VQuery<T = Data, AllowFn extends boolean = true> {
     /** logic path, dir or file, depends on context */
     collection?: string;
-    search?: Search<T>;
+    search?: Search<T, AllowFn>;
     context?: VContext;
     dbFindOpts?: DbFindOpts<T>;
     findOpts?: FindOpts<T>;
     data?: Arg<T>;
     id_gen?: boolean;
     add_arg?: Arg<T>;
-    updater?: Updater<T>;
+    updater?: Updater<T, AllowFn>;
     control?: VQuery_Control;
 }
 export declare namespace VQueryT {
-    type QueryBase<T = Data> = Required<Pick<VQuery<T>, "collection" | "search">> & Pick<VQuery<T>, "control">;
-    type Add<T = Data> = Required<Pick<VQuery<T>, "data" | "collection">> & Pick<VQuery<T>, "id_gen" | "control">;
-    type Find<T = Data> = Omit<QueryBase, "search"> & Pick<VQuery<T>, "search"> & Pick<VQuery<T>, "findOpts" | "dbFindOpts" | "context">;
-    type FindOne<T = Data> = QueryBase & Pick<VQuery<T>, "findOpts" | "context">;
-    type Update<T = Data> = QueryBase & Required<Pick<VQuery<T>, "updater">> & Pick<VQuery<T>, "context">;
-    type Remove<T = Data> = QueryBase & Pick<VQuery<T>, "context">;
-    type UpdateOneOrAdd<T = Data> = QueryBase & Update & Pick<VQuery<T>, "add_arg" | "id_gen">;
-    type ToggleOne<T = Data> = QueryBase & Pick<VQuery<T>, "data" | "context">;
+    type QueryBase<T = Data> = {
+        collection: string;
+        control?: VQuery_Control;
+    };
+    type Add<T = Data> = QueryBase<T> & {
+        data: Arg<T>;
+        id_gen?: boolean;
+    };
+    type Find<T = Data, AllowFn extends boolean = true> = QueryBase<T> & {
+        search?: Search<T, AllowFn>;
+        findOpts?: FindOpts<T>;
+        dbFindOpts?: DbFindOpts<T>;
+        context?: VContext;
+    };
+    type FindOne<T = Data, AllowFn extends boolean = true> = QueryBase<T> & {
+        search: Search<T, AllowFn>;
+        findOpts?: FindOpts<T>;
+        context?: VContext;
+    };
+    type Update<T = Data, AllowFn extends boolean = true> = QueryBase<T> & {
+        search: Search<T, AllowFn>;
+        updater: Updater<T, AllowFn>;
+        context?: VContext;
+    };
+    type Remove<T = Data, AllowFn extends boolean = true> = QueryBase<T> & {
+        search: Search<T, AllowFn>;
+        context?: VContext;
+    };
+    type UpdateOneOrAdd<T = Data, AllowFn extends boolean = true> = QueryBase<T> & {
+        search: Search<T, AllowFn>;
+        updater: Updater<T, AllowFn>;
+        add_arg?: Arg<T>;
+        id_gen?: boolean;
+        context?: VContext;
+    };
+    type ToggleOne<T = Data, AllowFn extends boolean = true> = QueryBase<T> & {
+        search: Search<T, AllowFn>;
+        data: Arg<T>;
+        context?: VContext;
+    };
     interface UpdateOneOrAddResult<T> {
         data: T;
         type: "added" | "updated";

package/dist/utils/action.d.ts

@@ -1,4 +1,4 @@
 import { Data } from "../types/data.js";
 import { FileCpu } from "../types/fileCpu.js";
 import { VQueryT } from "../types/query.js";
-export declare function findUtil(query: VQueryT.Find, fileCpuOrData: FileCpu | Object[], files: string[]): Promise<Data[]>;
+export declare function findUtil(query: VQueryT.Find, fileCpuOrData: FileCpu | Object[], files: string[], fileCpuOpts?: any): Promise<Data[]>;

package/dist/utils/action.js

@@ -1,5 +1,5 @@
 import { compareSafe } from "./compare.js";
-export async function findUtil(query, fileCpuOrData, files) {
+export async function findUtil(query, fileCpuOrData, files, fileCpuOpts) {
     const { dbFindOpts = {} } = query;
     const { reverse = false, offset = 0, limit = -1, sortBy, sortAsc = true, min, max, avg, groupBy, count, } = dbFindOpts;
     const needsAllData = min || max || avg || groupBy || count || sortBy;
@@ -18,7 +18,7 @@ export async function findUtil(query, fileCpuOrData, files) {
     else {
         const filesToProcess = reverse && !sortBy ? [...files].reverse() : files;
         for (const f of filesToProcess) {
-            let entries = await fileCpuOrData.find(f, query);
+            let entries = await fileCpuOrData.find(f, query, fileCpuOpts);
             if (reverse && !sortBy)
                 entries.reverse();
             if (needsAllData) {

package/dist/version.js

@@ -1 +1 @@
-export const version = "0.11.0";
+export const version = "0.11.1-alpha.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wxn0brp/db-core",
-  "version": "0.11.0",
+  "version": "0.11.1-alpha.1",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
   "author": "wxn0brP",