@rushdb/javascript-sdk 0.17.1 → 1.0.1

package/dist/network/HttpClient.d.ts

@@ -21,7 +21,7 @@ export interface HttpClientResponseInterface {
     toStream: (streamCompleteCallback: () => void) => unknown;
 }
 export declare class HttpClient implements HttpClientInterface {
-    static CONNECTION_CLOSED_ERROR_CODES: string[];
+    static CONNECTION_CLOSED_ERROR_CODES: Array<string>;
     static TIMEOUT_ERROR_CODE: string;
     makeRequest(url: string, { headers, method, protocol, requestData, timeout }: MakeRequestConfig): Promise<HttpClientResponseInterface>;
     static makeTimeoutError(): TimeoutError;

package/dist/network/types.d.ts

@@ -1,4 +1,5 @@
+import type { MaybeArray } from '../types';
 export type RequestData<T extends Record<string, any> = Record<string, any>> = T;
-export type RequestHeaders = Record<string, number | string | string[]>;
-export type ResponseHeaderValue = string | string[];
+export type RequestHeaders = Record<string, number | MaybeArray<string>>;
+export type ResponseHeaderValue = MaybeArray<string>;
 export type ResponseHeaders = Record<string, ResponseHeaderValue>;

package/dist/sdk/errors.d.ts

@@ -1,3 +1,4 @@
+import type { SearchQuery } from '../types';
 export declare class UniquenessError extends Error {
     constructor(label: string, properties: any);
 }
@@ -5,5 +6,5 @@ export declare class EmptyTargetError extends Error {
     constructor(message: string);
 }
 export declare class NonUniqueResultError extends Error {
-    constructor(duplicateCount: number, searchParams: Record<string, any>);
+    constructor(duplicateCount: number, searchQuery: SearchQuery);
 }

package/dist/sdk/model.d.ts

@@ -1,13 +1,31 @@
 import type { SearchQuery, Schema, FlattenTypes, InferSchemaTypesRead, InferSchemaTypesWrite, MaybeArray } from '../types/index.js';
-import type { DBRecord, DBRecordInstance, DBRecordsArrayInstance, RelationDetachOptions, RelationOptions, RelationTarget } from './record.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>>;
 };
+/**
+ * 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> extends RestApiProxy {
     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.
+     *                        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);
     /** @description
      * Type helper for a draft version of the schema.
@@ -35,42 +53,164 @@ export declare class Model<S extends Schema = any> extends RestApiProxy {
      * 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;
-    find<Q extends SearchQuery<S> = SearchQuery<S>>(params?: Q & {
+    /**
+     * Converts a database record to a record instance 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>>;
+    /**
+     * 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>>;
-    findOne<Q extends SearchQuery<S> = SearchQuery<S>>(params?: 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, Q>>;
-    findById(id: string, transaction?: Transaction | string): Promise<DBRecordInstance<S, {
-        where: {
-            $id: string;
-        };
-    }>>;
-    findUniq<Q extends SearchQuery<S> = SearchQuery<S>>(params?: Q & {
+    }, 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>>>;
-    attach(sourceId: string, target: RelationTarget, options?: RelationOptions, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{
+    /**
+     * 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;
-    }, Record<string, any>>>;
-    detach(sourceId: string, target: RelationTarget, options?: RelationDetachOptions, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{
+    }>>;
+    /**
+     * 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;
-    }, Record<string, any>>>;
+    }>>;
+    /**
+     * 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;
-    set(id: string, record: InferSchemaTypesWrite<S>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>;
-    update(id: string, record: Partial<InferSchemaTypesWrite<S>>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>;
-    createMany(records: InferSchemaTypesWrite<S>[], transaction?: Transaction | string): Promise<DBRecordsArrayInstance<S, SearchQuery<S>>>;
-    delete(searchParams: Omit<SearchQuery<S>, 'labels'>, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{
+    /**
+     * 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;
-    }, Record<string, any>>>;
+    }>>;
+    /**
+     * 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;
-    }, Record<string, any>>>;
+    }>>;
 }
+/**
+ * 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']>>;
 export {};

package/dist/sdk/record.d.ts

@@ -1,4 +1,4 @@
-import type { AnyObject, ExtractAggregateFields, FlattenTypes, InferSchemaTypesRead, InferSchemaTypesWrite, MaybeArray, OptionalKeysRead, PropertyType, PropertyValue, PropertyWithValue, RequiredKeysRead, Schema, SearchQuery } from '../types/index.js';
+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';
 type DBRecordInternalProps<S extends Schema = Schema> = {
@@ -33,84 +33,40 @@ export type RelationOptions = {
 };
 export type RelationDetachOptions = {
     direction?: RelationDirection;
-    typeOrTypes?: string | string[];
+    typeOrTypes?: MaybeArray<string>;
+};
+export type DBRecordCreationOptions = {
+    returnResult?: boolean;
+    suggestTypes?: boolean;
+    castNumberArraysToVectors?: boolean;
+    convertNumericValuesToNumbers?: boolean;
+    capitalizeLabels?: boolean;
+    relationshipType?: string;
 };
-export declare class DBRecordsBatchDraft {
-    label: string;
-    options?: {
-        returnResult?: boolean;
-        suggestTypes?: boolean;
-    };
-    payload: MaybeArray<AnyObject>;
-    constructor({ label, options, payload }: {
-        label: string;
-        options?: {
-            returnResult?: boolean;
-            suggestTypes?: boolean;
-        };
-        payload: AnyObject;
-    });
-    toJson(): {
-        label: string;
-        options: {
-            returnResult?: boolean;
-            suggestTypes?: boolean;
-        } | undefined;
-        payload: MaybeArray<AnyObject>;
-    };
-}
-export declare class DBRecordDraft {
-    label: string;
-    properties?: Array<{
-        metadata?: string;
-        name: string;
-        type: PropertyType;
-        value: PropertyValue;
-        valueSeparator?: string;
-    }>;
-    constructor({ label, properties }: {
-        label: string;
-        properties?: Array<PropertyWithValue & {
-            metadata?: string;
-            valueSeparator?: string;
-        }>;
-        relation?: RelationOptions;
-    });
-    toJson(): {
-        label: string;
-        properties: {
-            metadata?: string;
-            name: string;
-            type: PropertyType;
-            value: PropertyValue;
-            valueSeparator?: string;
-        }[] | undefined;
-    };
-}
 export declare class DBRecordInstance<S extends Schema = Schema, Q extends SearchQuery<S> = SearchQuery<S>> extends RestApiProxy {
     data?: DBRecordInferred<S, Q>;
     constructor(data?: DBRecordInferred<S, Q>);
-    get id(): string;
-    get label(): string;
-    get proptypes(): FlattenTypes<FlattenTypes<{ [Key in RequiredKeysRead<S>]: S[Key]["type"]; } & { [Key_1 in OptionalKeysRead<S>]?: S[Key_1]["type"] | undefined; }>> | undefined;
-    get date(): Date;
-    get timestamp(): number;
+    id(): string;
+    label(): string;
+    proptypes(): FlattenTypes<FlattenTypes<{ [Key in RequiredKeysRead<S>]: S[Key]["type"]; } & { [Key_1 in OptionalKeysRead<S>]?: S[Key_1]["type"] | undefined; }>> | undefined;
+    date(): Date;
+    timestamp(): number;
     delete(transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{
         message: string;
-    }, Record<string, any>>>;
-    update<S extends Schema = Schema>(partialData: DBRecordDraft | Partial<InferSchemaTypesWrite<S>>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>;
-    set<S extends Schema = Schema>(data: DBRecordDraft | InferSchemaTypesWrite<S>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>;
+    }>>;
+    update<S extends Schema = Schema>(data: Partial<InferSchemaTypesWrite<S>> | Array<PropertyDraft>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>;
+    set<S extends Schema = Schema>(data: InferSchemaTypesWrite<S> | Array<PropertyDraft>, transaction?: Transaction | string): Promise<DBRecordInstance<S, SearchQuery<S>>>;
     attach(target: RelationTarget, options?: RelationOptions, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{
         message: string;
-    }, Record<string, any>>>;
+    }>>;
     detach(target: RelationTarget, options?: RelationDetachOptions, transaction?: Transaction | string): Promise<import("../index.node.js").ApiResponse<{
         message: string;
-    }, Record<string, any>>>;
+    }>>;
 }
 export declare class DBRecordsArrayInstance<S extends Schema = Schema, Q extends SearchQuery<S> = SearchQuery<S>> extends RestApiProxy {
-    data?: DBRecordInferred<S, Q>[];
+    data?: Array<DBRecordInstance<S, Q>>;
     total: number | undefined;
-    searchParams?: SearchQuery<S>;
-    constructor(data?: DBRecordInferred<S, Q>[], total?: number, searchParams?: SearchQuery<S>);
+    searchQuery?: SearchQuery<S>;
+    constructor(data?: Array<DBRecordInstance<S, Q>>, total?: number, searchQuery?: SearchQuery<S>);
 }
 export {};