@rushdb/javascript-sdk

import type { SearchQuery, Schema, FlattenTypes, InferSchemaTypesRead, InferSchemaTypesWrite, MaybeArray } from '../types/index.js'; import type { DBRecord, DBRecordInstance, DBRecordsArrayInstance, DBRecordTarget, RelationDetachOptions, RelationOptions, RelationTarget } from './record.js'; import type { Transaction } from './transaction.js'; import { RushDB } from './sdk'; /** * Represents a model in the RushDB database. * A model defines the structure and behavior of a specific type of record in the database. * It provides methods for CRUD operations and relationship management. * * @typeParam S - The schema type that defines the structure of the model's records */ export declare class Model<S extends Schema = any> { readonly label: string; readonly schema: S; /** * Creates a new Model instance. * * @param modelName - The name/label of the model in the database * @param schema - The schema definition that describes the model's structure * @param rushDBInstance - Optional RushDB instance for model registration. * This is the recommended way to register models as it automatically * registers the model with the RushDB instance during creation. */ constructor(modelName: string, schema: S); /** @description * Type helper for a draft version of the schema. * Represents a flat object containing only the record's own properties * (defined by the schema), excluding system fields such as `__id`, `__label`, * and `__proptypes`. This type does not yet have a representation on the * database side. */ readonly draft: InferType<Model<S>>; /** @description * Type helper for a SearchQuery of the schema. * Represents a structured query input that enables filtering, * sorting, pagination, and aggregation of records based on schema-defined fields. * Useful for composing reusable, type-safe search expressions. */ readonly searchQuery: SearchQuery<S>; /** @description * Type helper for a fully defined record with database representation. * Similar to the draft, but includes all fields that come with the record's * database-side representation, such as `__id`, `__label`, and `__proptypes`. */ readonly record: DBRecord<S>; /** @description * Type helper for a single record instance. * Extends the record by providing additional methods to operate on this specific * record, such as saving, updating, or deleting it. */ readonly recordInstance: DBRecordInstance<S>; /** @description * Type helper for an array of record instances. * Similar to a single record instance but supports batch or bulk operations, * allowing efficient management of multiple records simultaneously. */ readonly recordsArrayInstance: DBRecordsArrayInstance<S>; /** * Retrieves the model's label. * * @returns The label/name of the model */ getLabel(): string; /** * Retrieves the initialized RushDB instance or waits for initialization to complete. * * This method is called internally by all data access methods in the Model class. * It ensures that the database connection is properly established before executing * any operations. For this to work, make sure you've created a RushDB instance * somewhere in your code and imported that module in your application's entry point. * * Note: If you get "No RushDB instance found" errors, it usually means the module * where you create your RushDB instance hasn't been imported yet. * * @returns Promise resolving to the initialized RushDB instance * @throws Error if no RushDB instance has been created yet */ getRushDBInstance(): Promise<RushDB>; /** * Converts a database record to a record instance (DBRecordInstance) with additional methods. * * @param record - The database record to convert * @returns A record instance with additional methods * @throws Error if no RushDB instance was provided during initialization */ toDBRecordInstance(record: DBRecord<S>): Promise<DBRecordInstance<Schema, SearchQuery<Schema>>>; /** * Finds records that match the given search criteria. * * @param searchQuery - Optional search criteria * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to matching records */ find<Q extends SearchQuery<S> = SearchQuery<S>>(searchQuery?: Q & { labels?: never; }, transaction?: Transaction | string): Promise<DBRecordsArrayInstance<S, Q>>; /** * Finds a single record that matches the given search criteria. * * @param searchQuery - Optional search criteria * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the matching record or null if not found */ findOne<Q extends SearchQuery<S> = SearchQuery<S>>(searchQuery?: Q & { labels?: never; limit?: never; skip?: never; }, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>; /** * Finds a record by its ID. * * @param id - The ID of the record to find * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the matching record or null if not found */ findById(id: string, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>; /** * Finds a unique record that matches the given search criteria. * * @param searchQuery - Optional search criteria * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the unique matching record or null if not found */ findUniq<Q extends SearchQuery<S> = SearchQuery<S>>(searchQuery?: Q & { labels?: never; limit?: never; skip?: never; }, transaction?: Transaction | string): Promise<DBRecordInstance<S, Q>>; /** * Creates a new record in the database. * * @param record - The record data to create * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the created record * @throws UniquenessError if the record violates uniqueness constraints */ create(record: InferSchemaTypesWrite<S>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>; /** * Attaches a relationship between records. * * @param params - Object containing source, target, and relationship options * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the result of the attach operation */ attach({ source, target, options }: { source: DBRecordTarget; target: RelationTarget; options?: RelationOptions; }, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{ message: string; }>>; /** * Detaches a relationship between records. * * @param params - Object containing source, target, and detach options * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the result of the detach operation */ detach({ source, target, options }: { source: DBRecordTarget; target: RelationTarget; options?: RelationDetachOptions; }, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{ message: string; }>>; /** * Internal method to handle both set and update operations. * * @param target - The target record to modify * @param record - The data to set or update * @param method - The operation type ('set' or 'update') * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the modified record * @throws UniquenessError if the modification violates uniqueness constraints * @private */ private handleSetOrUpdate; /** * Sets all fields of a record to the provided values. * * @param target - The target record to modify * @param record - The new values to set * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the modified record */ set(target: DBRecordTarget, record: InferSchemaTypesWrite<S>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>; /** * Updates specified fields of a record. * * @param target - The target record to modify * @param record - The fields to update and their new values * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the modified record */ update(target: DBRecordTarget, record: Partial<InferSchemaTypesWrite<S>>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>; /** * Creates multiple records in a single operation. * * @param records - Array of records to create * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the created records * @throws UniquenessError if any record violates uniqueness constraints */ createMany(records: Array<InferSchemaTypesWrite<S>>, transaction?: Transaction | string): Promise<DBRecordsArrayInstance<S, SearchQuery<S>>>; /** * Deletes records that match the given search criteria. * * @param searchQuery - Search criteria for records to delete * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the result of the delete operation * @throws EmptyTargetError if no search criteria are provided */ delete(searchQuery: Omit<SearchQuery<S>, 'labels'>, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{ message: string; }>>; /** * Deletes one or more records by their IDs. * * @param idOrIds - Single ID or array of IDs to delete * @param transaction - Optional transaction or transaction ID * @returns Promise resolving to the result of the delete operation */ deleteById(idOrIds: MaybeArray<string>, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{ message: string; }>>; } /** * Helper type that infers the type structure from a Model instance. * * @typeParam M - The Model type to infer from */ export type InferType<M extends Model<any> = Model<any>> = FlattenTypes<InferSchemaTypesRead<M['schema']>>;