@push.rocks/smartdata
Version:
An advanced library for NoSQL data organization and manipulation using TypeScript with support for MongoDB, data validation, collections, and custom data types.
218 lines (217 loc) • 7.7 kB
TypeScript
import * as plugins from './plugins.js';
import { SmartdataDbCursor } from './classes.cursor.js';
import { type IManager, SmartdataCollection } from './classes.collection.js';
import { SmartdataDbWatcher } from './classes.watcher.js';
/**
* Search options for `.search()`:
* - filter: additional MongoDB query to AND-merge
* - validate: post-fetch validator, return true to keep a doc
*/
export interface SearchOptions<T> {
/**
* Additional MongoDB filter to AND‐merge into the query
*/
filter?: Record<string, any>;
/**
* Post‐fetch validator; return true to keep each doc
*/
validate?: (doc: T) => Promise<boolean> | boolean;
/**
* Optional MongoDB session for transactional operations
*/
session?: plugins.mongodb.ClientSession;
}
export type TDocCreation = 'db' | 'new' | 'mixed';
export declare function globalSvDb(): (target: SmartDataDbDoc<unknown, unknown>, key: string) => void;
/**
* Options for custom serialization/deserialization of a field.
*/
export interface SvDbOptions {
/** Function to serialize the field value before saving to DB */
serialize?: (value: any) => any;
/** Function to deserialize the field value after reading from DB */
deserialize?: (value: any) => any;
}
/**
* saveable - saveable decorator to be used on class properties
*/
export declare function svDb(options?: SvDbOptions): (target: SmartDataDbDoc<unknown, unknown>, key: string) => void;
/**
* searchable - marks a property as searchable with Lucene query syntax
*/
export declare function searchable(): (target: SmartDataDbDoc<unknown, unknown>, key: string) => void;
/**
* unique index - decorator to mark a unique index
*/
export declare function unI(): (target: SmartDataDbDoc<unknown, unknown>, key: string) => void;
/**
* Options for MongoDB indexes
*/
export interface IIndexOptions {
background?: boolean;
unique?: boolean;
sparse?: boolean;
expireAfterSeconds?: number;
[key: string]: any;
}
/**
* index - decorator to mark a field for regular indexing
*/
export declare function index(options?: IIndexOptions): (target: SmartDataDbDoc<unknown, unknown>, key: string) => void;
export declare const convertFilterForMongoDb: (filterArg: {
[key: string]: any;
}) => {
[key: string]: any;
};
export declare class SmartDataDbDoc<T extends TImplements, TImplements, TManager extends IManager = any> {
/**
* the collection object an Doc belongs to
*/
static collection: SmartdataCollection<any>;
collection: SmartdataCollection<any>;
static defaultManager: any;
static manager: any;
manager: TManager;
static createInstanceFromMongoDbNativeDoc<T>(this: plugins.tsclass.typeFest.Class<T>, mongoDbNativeDocArg: any): T;
/**
* gets all instances as array
* @param this
* @param filterArg
* @returns
*/
static getInstances<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: plugins.tsclass.typeFest.PartialDeep<T>, opts?: {
session?: plugins.mongodb.ClientSession;
}): Promise<T[]>;
/**
* gets the first matching instance
* @param this
* @param filterArg
* @returns
*/
static getInstance<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: plugins.tsclass.typeFest.PartialDeep<T>, opts?: {
session?: plugins.mongodb.ClientSession;
}): Promise<T>;
/**
* get a unique id prefixed with the class name
*/
static getNewId<T = any>(this: plugins.tsclass.typeFest.Class<T>, lengthArg?: number): Promise<string>;
/**
* Get a cursor for streaming results, with optional session and native cursor modifiers.
* @param filterArg Partial filter to apply
* @param opts Optional session and modifier for the raw MongoDB cursor
*/
static getCursor<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: plugins.tsclass.typeFest.PartialDeep<T>, opts?: {
session?: plugins.mongodb.ClientSession;
modifier?: (cursorArg: plugins.mongodb.FindCursor<plugins.mongodb.WithId<plugins.mongodb.BSON.Document>>) => plugins.mongodb.FindCursor<plugins.mongodb.WithId<plugins.mongodb.BSON.Document>>;
}): Promise<SmartdataDbCursor<T>>;
/**
* watch the collection
* @param this
* @param filterArg
* @param forEachFunction
*/
static watch<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: plugins.tsclass.typeFest.PartialDeep<T>): Promise<SmartdataDbWatcher<T>>;
/**
* run a function for all instances
* @returns
*/
static forEach<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg: plugins.tsclass.typeFest.PartialDeep<T>, forEachFunction: (itemArg: T) => Promise<any>): Promise<void>;
/**
* returns a count of the documents in the collection
*/
static getCount<T>(this: plugins.tsclass.typeFest.Class<T>, filterArg?: plugins.tsclass.typeFest.PartialDeep<T>): Promise<number>;
/**
* Create a MongoDB filter from a Lucene query string
* @param luceneQuery Lucene query string
* @returns MongoDB query object
*/
static createSearchFilter<T>(this: plugins.tsclass.typeFest.Class<T>, luceneQuery: string): any;
/**
* List all searchable fields defined on this class
*/
static getSearchableFields(): string[];
/**
* Execute a query with optional hard filter and post-fetch validation
*/
private static execQuery;
/**
* Search documents by text or field:value syntax, with safe regex fallback
* Supports additional filtering and post-fetch validation via opts
* @param query A search term or field:value expression
* @param opts Optional filter and validate hooks
* @returns Array of matching documents
*/
static search<T>(this: plugins.tsclass.typeFest.Class<T>, query: string, opts?: SearchOptions<T>): Promise<T[]>;
/**
* how the Doc in memory was created, may prove useful later.
*/
creationStatus: TDocCreation;
/**
* updated from db in any case where doc comes from db
*/
_createdAt: string;
/**
* will be updated everytime the doc is saved
*/
_updatedAt: string;
/**
* an array of saveable properties of ALL doc
*/
globalSaveableProperties: string[];
/**
* unique indexes
*/
uniqueIndexes: string[];
/**
* regular indexes with their options
*/
regularIndexes: Array<{
field: string;
options: IIndexOptions;
}>;
/**
* an array of saveable properties of a specific doc
*/
saveableProperties: string[];
/**
* name
*/
name: string;
/**
* primary id in the database
*/
dbDocUniqueId: string;
/**
* class constructor
*/
constructor();
/**
* saves this instance (optionally within a transaction)
*/
save(opts?: {
session?: plugins.mongodb.ClientSession;
}): Promise<any>;
/**
* deletes a document from the database (optionally within a transaction)
*/
delete(opts?: {
session?: plugins.mongodb.ClientSession;
}): Promise<any>;
/**
* also store any referenced objects to DB
* better for data consistency
*/
saveDeep(savedMapArg?: plugins.lik.ObjectMap<SmartDataDbDoc<any, any>>): void;
/**
* updates an object from db
*/
updateFromDb(): Promise<void>;
/**
* creates a saveable object so the instance can be persisted as json in the database
*/
createSavableObject(): Promise<TImplements>;
/**
* creates an identifiable object for operations that require filtering
*/
createIdentifiableObject(): Promise<any>;
}