@rushdb/javascript-sdk 1.3.1 → 1.4.0

package/dist/sdk/model.d.ts

@@ -1,11 +1,7 @@
 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 { RestApiProxy } from '../api/rest-api-proxy.js';
-type RushDBInstance = {
-    registerModel(model: Model): void;
-    toInstance<S extends Schema = Schema>(record: DBRecord<S>): DBRecordInstance<S, SearchQuery<S>>;
-};
+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.
@@ -13,20 +9,19 @@ type RushDBInstance = {
  *
  * @typeParam S - The schema type that defines the structure of the model's records
  */
-export declare class Model<S extends Schema = any> extends RestApiProxy {
+export declare class Model<S extends Schema = any> {
     readonly label: string;
     readonly schema: S;
-    private readonly rushDBInstance?;
     /**
      * 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.
+     * @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, RushDBInstance?: RushDBInstance);
+    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
@@ -36,7 +31,14 @@ export declare class Model<S extends Schema = any> extends RestApiProxy {
      */
     readonly draft: InferType<Model<S>>;
     /** @description
-     * Type helper for a fully-defined record with database representation.
+     * 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`.
      */
@@ -60,13 +62,28 @@ export declare class Model<S extends Schema = any> extends RestApiProxy {
      */
     getLabel(): string;
     /**
-     * Converts a database record to a record instance with additional methods.
+     * 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
      */
-    toInstance(record: DBRecord<S>): DBRecordInstance<S, SearchQuery<S>>;
+    toDBRecordInstance(record: DBRecord<S>): Promise<DBRecordInstance<Schema, SearchQuery<Schema>>>;
     /**
      * Finds records that match the given search criteria.
      *
@@ -213,4 +230,3 @@ export declare class Model<S extends Schema = any> extends RestApiProxy {
  * @typeParam M - The Model type to infer from
  */
 export type InferType<M extends Model<any> = Model<any>> = FlattenTypes<InferSchemaTypesRead<M['schema']>>;
-export {};

package/dist/sdk/record.d.ts

@@ -1,6 +1,9 @@
 import type { ExtractAggregateFields, FlattenTypes, InferSchemaTypesRead, InferSchemaTypesWrite, MaybeArray, OptionalKeysRead, PropertyDraft, RequiredKeysRead, Schema, SearchQuery } from '../types/index.js';
 import type { Transaction } from './transaction.js';
-import { RestApiProxy } from '../api/rest-api-proxy.js';
+/**
+ * Internal properties that are present on all database records.
+ * These are system fields managed by RushDB.
+ */
 type DBRecordInternalProps<S extends Schema = Schema> = {
     readonly __id: string;
     readonly __label: string;
@@ -10,15 +13,36 @@ type DBRecordInternalProps<S extends Schema = Schema> = {
         [Key in OptionalKeysRead<S>]?: S[Key]['type'];
     }>;
 };
+/**
+ * Properties defined by the user's schema.
+ */
 export type RecordProps<S extends Schema = Schema> = S extends S ? InferSchemaTypesRead<S> : {
     [K in keyof S]?: S[K];
 };
+/**
+ * DBRecord with possible aggregation fields based on a search query.
+ */
 export type DBRecordInferred<S extends Schema, Q extends SearchQuery<S>> = Q extends {
     aggregate: infer A extends Record<string, any>;
 } ? DBRecord<S> & ExtractAggregateFields<A> : DBRecord<S>;
+/**
+ * Represents a database record with both system fields and user-defined fields.
+ * This is the raw data structure returned from database queries.
+ */
 export type DBRecord<S extends Schema = Schema> = FlattenTypes<DBRecordInternalProps<S> & FlattenTypes<RecordProps<S>>>;
+/**
+ * Target for operations like update, delete, etc.
+ * Can be a record object, a record instance, or a record ID.
+ */
 export type DBRecordTarget = DBRecord<any> | DBRecordInstance<any> | string;
+/**
+ * Target for relationship operations.
+ * Can be an array of records, record instances, or record IDs.
+ */
 export type RelationTarget = DBRecordsArrayInstance<any> | MaybeArray<DBRecord<any>> | MaybeArray<DBRecordInstance<any>> | MaybeArray<string>;
+/**
+ * Represents a relationship between two records.
+ */
 export type Relation = {
     sourceId: string;
     sourceLabel: string;
@@ -26,15 +50,28 @@ export type Relation = {
     targetLabel: string;
     type: string;
 };
+/**
+ * Direction of a relationship.
+ * 'in' for incoming relationships, 'out' for outgoing relationships.
+ */
 export type RelationDirection = 'in' | 'out';
+/**
+ * Options for creating or modifying relationships.
+ */
 export type RelationOptions = {
     direction?: RelationDirection;
     type?: string;
 };
+/**
+ * Options for detaching (removing) relationships.
+ */
 export type RelationDetachOptions = {
     direction?: RelationDirection;
     typeOrTypes?: MaybeArray<string>;
 };
+/**
+ * Options for creating database records.
+ */
 export type DBRecordCreationOptions = {
     returnResult?: boolean;
     suggestTypes?: boolean;
@@ -43,30 +80,136 @@ export type DBRecordCreationOptions = {
     capitalizeLabels?: boolean;
     relationshipType?: string;
 };
-export declare class DBRecordInstance<S extends Schema = Schema, Q extends SearchQuery<S> = SearchQuery<S>> extends RestApiProxy {
-    data?: DBRecordInferred<S, Q>;
+export declare class DBRecordInstance<S extends Schema = Schema, Q extends SearchQuery<S> = SearchQuery<S>> {
+    data: DBRecordInferred<S, Q>;
+    /**
+     * Creates a new DBRecordInstance.
+     * Typically, you don't create these directly but receive them from query results.
+     *
+     * @param data - The raw record data
+     */
     constructor(data?: DBRecordInferred<S, Q>);
+    /**
+     *
+     * Checks if this record instance exists.
+     * A record is considered to exist if it has a valid ID and label.
+     *
+     * @returns True if the record exists, false otherwise
+     */
+    exists(): boolean;
+    /**
+     * Gets the unique ID of this record.
+     *
+     * @returns The record's ID
+     * @throws Error if the ID is missing or invalid
+     */
     id(): string;
+    /**
+     * Gets the label (type) of this record.
+     *
+     * @returns The record's label
+     * @throws Error if the label is missing or invalid
+     */
     label(): string;
+    /**
+     * Gets the property types of this record.
+     *
+     * @returns The record's property types
+     * @throws Error if the property types are missing or invalid
+     */
     proptypes(): FlattenTypes<FlattenTypes<{ [Key in RequiredKeysRead<S>]: S[Key]["type"]; } & { [Key_1 in OptionalKeysRead<S>]?: S[Key_1]["type"] | undefined; }>> | undefined;
+    /**
+     * Gets the creation date of this record.
+     * The date is derived from the record's ID.
+     *
+     * @returns The record's creation date
+     * @throws Error if the ID is missing or invalid
+     */
     date(): Date;
+    /**
+     * Gets the creation timestamp of this record.
+     * The timestamp is derived from the record's ID.
+     *
+     * @returns The record's creation timestamp
+     * @throws Error if the ID is missing or invalid
+     */
     timestamp(): number;
+    /**
+     * Deletes this record from the database.
+     *
+     * @param transaction - Optional transaction or transaction ID
+     * @returns Promise resolving to the result of the delete operation
+     * @throws Error if the record data is undefined
+     */
     delete(transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{
         message: string;
     }>>;
+    /**
+     * Updates specific fields of this record.
+     *
+     * @param data - The fields to update and their new values
+     * @param transaction - Optional transaction or transaction ID
+     * @returns Promise resolving to the updated record
+     * @throws Error if the record data is undefined
+     */
     update<S extends Schema = Schema>(data: Partial<InferSchemaTypesWrite<S>> | Array<PropertyDraft>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>;
+    /**
+     * Sets all fields of this record to the provided values.
+     * This replaces all existing field values.
+     *
+     * @param data - The new field values
+     * @param transaction - Optional transaction or transaction ID
+     * @returns Promise resolving to the updated record
+     * @throws Error if the record data is undefined
+     */
     set<S extends Schema = Schema>(data: InferSchemaTypesWrite<S> | Array<PropertyDraft>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>;
+    /**
+     * Creates a relationship between this record and another record or records.
+     *
+     * @param target - The target record(s) to create a relationship with
+     * @param options - Optional relationship options
+     * @param transaction - Optional transaction or transaction ID
+     * @returns Promise resolving to the result of the attach operation
+     * @throws Error if the record data is undefined
+     */
     attach(target: RelationTarget, options?: RelationOptions, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{
         message: string;
     }>>;
+    /**
+     * Removes a relationship between this record and another record or records.
+     *
+     * @param target - The target record(s) to remove the relationship from
+     * @param options - Optional detach options
+     * @param transaction - Optional transaction or transaction ID
+     * @returns Promise resolving to the result of the detach operation
+     * @throws Error if the record data is undefined
+     */
     detach(target: RelationTarget, options?: RelationDetachOptions, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{
         message: string;
     }>>;
 }
-export declare class DBRecordsArrayInstance<S extends Schema = Schema, Q extends SearchQuery<S> = SearchQuery<S>> extends RestApiProxy {
-    data?: Array<DBRecordInstance<S, Q>>;
-    total: number | undefined;
+/**
+ * Represents a collection of database records with additional methods for batch operations.
+ * This class is typically returned from queries that match multiple records.
+ *
+ * @typeParam S - The schema type that defines the records' structure
+ * @typeParam Q - The search query type that was used to retrieve these records
+ */
+export declare class DBRecordsArrayInstance<S extends Schema = Schema, Q extends SearchQuery<S> = SearchQuery<S>> {
+    /** The array of record instances */
+    data: Array<DBRecordInstance<S, Q>>;
+    /** The total number of records matching the query (may be more than the number in data) */
+    total: number;
+    /** The search query that was used to retrieve these records */
     searchQuery?: SearchQuery<S>;
+    /**
+     * Creates a new DBRecordsArrayInstance.
+     * Typically, you don't create these directly but receive them from query results.
+     *
+     * @param data - The array of record instances
+     * @param total - The total number of records matching the query
+     * @param searchQuery - The search query that was used to retrieve these records
+     */
     constructor(data?: Array<DBRecordInstance<S, Q>>, total?: number, searchQuery?: SearchQuery<S>);
 }
 export {};