@wxn0brp/vql-client 0.2.7 → 0.2.9

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 wxn0brP
+Copyright (c) 2026 wxn0brP
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -9,6 +9,12 @@ Supports:
 - Fully typed with TypeScript
 - Custom transport layers and lifecycle hooks
 
+## Installation
+
+```bash
+npm install @wxn0brp/vql-client
+```
+
 ## DOCS
 
 [API Reference](https://wxn0brp.github.io/VQL-client/)
@@ -32,9 +38,7 @@ const result = await fetchVQL("db1 user! s._id = xyz");
 </script>
 ```
 
-## Usage
-
-### `fetchVQL<T = any>(query: string | object, vars?: Object, hookContext?: Object): Promise<T>`
+### `fetchVQL<T = any>(query: string | object, vars?: Object, hookContext?: Object, fetchOptions?: FetchOptions): Promise<T>`
 
 Executes a VQL query and returns the result (unwrapped from `{ result }`, unless an error is present).
 
@@ -82,10 +86,16 @@ Returns:
 }
 ```
 
+## About Releases
+
+Some releases may not have associated source code commits (e.g., `0.2.8`, `0.2.7`). These releases contain type definition updates only.
+
+The `vql.d.ts` file is not maintained in this repository. During the release process, it is fetched (via `curl`) from the main project repository and included in the published package. If only the external type definitions change, a new version is published without modifying this repository’s source code.
+
 ## License
 
-MIT wxn0brP
+MIT. See [LICENSE](./LICENSE)
 
 ## Contributing
 
-Contributions are welcome!
+Contributions are welcome!

package/dist/vql.d.ts

@@ -1,9 +1,6 @@
 export interface Data {
     [key: string]: any;
 }
-export interface VContext {
-    [key: string]: any;
-}
 export type KeysMatching<T, V, C = V> = {
     [K in keyof T]-?: T[K] extends C ? K : never;
 }[keyof T];
@@ -13,6 +10,7 @@ export type NestedValue<T, V, C = V> = {
 export type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
+export type JSPrimitiveType = "string" | "number" | "boolean" | "bigint" | "symbol" | "undefined" | "function" | "object";
 export type LogicalOperators<T = any> = {
     $and?: Array<SearchOptions<T>>;
     $or?: Array<SearchOptions<T>>;
@@ -39,8 +37,8 @@ export type ComparisonOperators<T = any> = {
     $idLte?: NestedValue<T, string | number, string | number>;
 };
 export type TypeAndExistenceOperators<T = any> = {
-    $exists?: NestedValue<T, boolean>;
-    $type?: NestedValue<T, string>;
+    $exists?: NestedValue<T, boolean, any>;
+    $type?: NestedValue<T, JSPrimitiveType, any>;
 };
 export type ArrayOperators<T = any> = {
     $arrinc?: DeepPartial<T>;
@@ -57,6 +55,9 @@ export type OtherOperators<T = any> = {
 };
 export type PredefinedSearchOperators<T = any> = LogicalOperators<T> & ComparisonOperators<T> & TypeAndExistenceOperators<T> & ArrayOperators<T> & StringOperators<T> & OtherOperators<T>;
 export type SearchOptions<T = any> = PredefinedSearchOperators<T> & DeepPartial<T> & Record<string, any>;
+export interface VContext {
+    [key: string]: any;
+}
 export type ArrayUpdater<T = any> = {
     $push?: NestedValue<T, any>;
     $pushset?: NestedValue<T, any>;
@@ -82,6 +83,41 @@ export type SearchFunc<T = any> = (data: T, context: VContext) => boolean;
 export type UpdaterFunc<T = any> = (data: T, context: VContext) => boolean;
 export type Search<T = any> = SearchOptions<T> | SearchFunc<T>;
 export type Updater<T = any> = UpdaterArg<T> | UpdaterArg<T>[] | UpdaterFunc<T>;
+export interface UpdateOneOrAdd<T> {
+    add_arg?: Arg<T>;
+    id_gen?: boolean;
+    context?: VContext;
+}
+export interface VQuery_Control {
+}
+export interface VQuery<T = Data> {
+    collection?: string;
+    search?: Search<T>;
+    context?: VContext;
+    dbFindOpts?: DbFindOpts<T>;
+    findOpts?: FindOpts<T>;
+    data?: Arg<T>;
+    id_gen?: boolean;
+    add_arg?: Arg<T>;
+    updater?: Updater<T>;
+    control?: VQuery_Control;
+}
+export type QueryBase<T = Data> = Required<Pick<VQuery<T>, "collection" | "search">> & Pick<VQuery<T>, "control">;
+export type AddQuery<T = Data> = Required<Pick<VQuery<T>, "data" | "collection">> & Pick<VQuery<T>, "id_gen" | "control">;
+export type FindQuery<T = Data> = Omit<QueryBase, "search"> & Pick<VQuery<T>, "search"> & Pick<VQuery<T>, "findOpts" | "dbFindOpts" | "context">;
+export type FindOneQuery<T = Data> = QueryBase & Pick<VQuery<T>, "findOpts" | "context">;
+export type UpdateQuery<T = Data> = QueryBase & Required<Pick<VQuery<T>, "updater">> & Pick<VQuery<T>, "context">;
+export type RemoveQuery<T = Data> = QueryBase & Pick<VQuery<T>, "context">;
+export type UpdateOneOrAddQuery<T = Data> = QueryBase & UpdateQuery & Pick<VQuery<T>, "add_arg" | "id_gen">;
+export type ToggleOneQuery<T = Data> = QueryBase & Pick<VQuery<T>, "data" | "context">;
+export interface UpdateOneOrAddResult<T> {
+    data: T;
+    type: "added" | "updated";
+}
+export interface ToggleOneResult<T> {
+    data: T;
+    type: "added" | "removed";
+}
 export interface DbFindOpts<T = any> {
     reverse?: boolean;
     limit?: number;
@@ -94,40 +130,44 @@ export interface FindOpts<T = any> {
     exclude?: KeysMatching<T, any>[];
     transform?: Function;
 }
-declare class CollectionManager<D = Data> {
-    private db;
-    private collection;
+declare class Collection<D = Data> {
+    db: ValtheraCompatible;
+    collection: string;
     constructor(db: ValtheraCompatible, collection: string);
-    add<T = Data>(data: Arg<T & D>, id_gen?: boolean): Promise<T>;
-    find<T = Data>(search?: Search<T & D>, options?: DbFindOpts<T & D>, findOpts?: FindOpts<T & D>, context?: VContext): Promise<T[]>;
-    findOne<T = Data>(search?: Search<T & D>, findOpts?: FindOpts<T & D>, context?: VContext): Promise<T>;
-    update<T = Data>(search: Search<T & D>, updater: Updater<T & D>, context?: VContext): Promise<boolean>;
-    updateOne<T = Data>(search: Search<T & D>, updater: Updater<T & D>, context?: VContext): Promise<boolean>;
-    remove<T = Data>(search: Search<T & D>, context?: VContext): Promise<boolean>;
-    removeOne<T = Data>(search: Search<T & D>, context?: VContext): Promise<boolean>;
-    updateOneOrAdd<T = Data>(search: Search<T & D>, updater: Updater<T & D>, { add_arg, context, id_gen }: UpdateOneOrAdd<T & D>): Promise<boolean>;
-    toggleOne<T = Data>(search: Search<T & D>, data?: Arg<T & D>, context?: VContext): Promise<boolean>;
+    add(data: Arg<D>, id_gen: false): Promise<D>;
+    add(data: Arg<D>, id_gen?: true): Promise<D & {
+        _id: string;
+    }>;
+    find(search?: Search<D>, options?: DbFindOpts<D>, findOpts?: FindOpts<D>, context?: VContext): Promise<D[]>;
+    findOne(search?: Search<D>, findOpts?: FindOpts<D>, context?: VContext): Promise<D>;
+    update(search: Search<D>, updater: Updater<D>, context?: VContext): Promise<D[]>;
+    updateOne(search: Search<D>, updater: Updater<D>, context?: VContext): Promise<D | null>;
+    remove(search: Search<D>, context?: VContext): Promise<D[]>;
+    removeOne(search: Search<D>, context?: VContext): Promise<D | null>;
+    updateOneOrAdd(search: Search<D>, updater: Updater<D>, { add_arg, context, id_gen }?: UpdateOneOrAdd<D>): Promise<UpdateOneOrAddResult<D>>;
+    toggleOne(search: Search<D>, data?: Arg<D>, context?: VContext): Promise<ToggleOneResult<D>>;
 }
 export interface ValtheraCompatible {
-    c(collection: string): CollectionManager;
+    c<T = Data>(collection: string): Collection<T>;
     getCollections(): Promise<string[]>;
     ensureCollection(collection: string): Promise<boolean>;
     issetCollection(collection: string): Promise<boolean>;
-    add<T = Data>(collection: string, data: Arg<T>, id_gen?: boolean): Promise<T>;
-    find<T = Data>(collection: string, search?: Search<T>, options?: DbFindOpts<T>, findOpts?: FindOpts<T>, context?: VContext): Promise<T[]>;
-    findOne<T = Data>(collection: string, search?: Search<T>, findOpts?: FindOpts<T>, context?: VContext): Promise<T | null>;
-    update<T = Data>(collection: string, search: Search<T>, updater: Updater<T>, context?: VContext): Promise<boolean>;
-    updateOne<T = Data>(collection: string, search: Search<T>, updater: Updater<T>, context?: VContext): Promise<boolean>;
-    remove<T = Data>(collection: string, search: Search<T>, context?: VContext): Promise<boolean>;
-    removeOne<T = Data>(collection: string, search: Search<T>, context?: VContext): Promise<boolean>;
+    add<T = Data>(query: AddQuery<T>): Promise<T>;
+    find<T = Data>(query: FindQuery<T>): Promise<T[]>;
+    findOne<T = Data>(query: FindOneQuery<T>): Promise<T | null>;
+    update<T = Data>(query: UpdateQuery<T>): Promise<T[]>;
+    updateOne<T = Data>(query: UpdateQuery<T>): Promise<T | null>;
+    remove<T = Data>(query: RemoveQuery<T>): Promise<T[]>;
+    removeOne<T = Data>(query: RemoveQuery<T>): Promise<T | null>;
     removeCollection(collection: string): Promise<boolean>;
-    updateOneOrAdd<T = Data>(collection: string, search: Search<T>, updater: Updater<T>, opts?: UpdateOneOrAdd<T>): Promise<boolean>;
-    toggleOne<T = Data>(collection: string, search: Search<T>, data?: Arg<T>, context?: VContext): Promise<boolean>;
+    updateOneOrAdd<T = Data>(query: UpdateOneOrAddQuery<T>): Promise<UpdateOneOrAddResult<T>>;
+    toggleOne<T = Data>(query: ToggleOneQuery<T>): Promise<ToggleOneResult<T>>;
 }
-export interface UpdateOneOrAdd<T> {
-    add_arg?: Arg<T>;
-    id_gen?: boolean;
-    context?: VContext;
+export interface VQuery_Control {
+    dir?: {
+        lastFileNum?: number;
+        sortedFiles?: string[];
+    };
 }
 declare namespace RelationTypes {
     type Path = [
@@ -147,7 +187,7 @@ declare namespace RelationTypes {
         fk?: string;
         as?: string;
         select?: string[];
-        findOpts?: DbFindOpts;
+        dbFindOpts?: DbFindOpts;
         type?: "1" | "11" | "1n" | "nm";
         relations?: Relation;
         through?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wxn0brp/vql-client",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "description": "VQL Client",