frappe-js-client
Version:
Next-generation TS/JS client for Frappe REST APIs, built on axios for robust, type-safe integration.
256 lines (255 loc) • 8.33 kB
TypeScript
/**
* @module db
* @description Provides database operations for Frappe documents.
* This module handles CRUD operations, document listing, counting, and querying
* with support for filtering, pagination, and sorting.
*
* @packageDocumentation
*
* @example
* ```typescript
* import { FrappeApp } from '@frappe/sdk';
*
* const app = new FrappeApp('https://instance.example.com');
* const db = app.db();
*
* // Get a document
* const user = await db.getDoc('User', 'administrator');
*
* // Get a filtered list of documents
* const tasks = await db.getDocList('Task', {
* filters: [['status', '=', 'Open']],
* orderBy: { field: 'creation', order: 'desc' }
* });
* ```
*/
import { AxiosInstance } from 'axios';
import { Filter, FrappeDoc, GetDocListArgs, GetLastDocArgs } from './types';
/**
* Main class for database operations in Frappe.
*
* @class FrappeDB
* @description Provides methods for interacting with Frappe's database,
* including CRUD operations and document querying.
*
* @example
* ```typescript
* const db = new FrappeDB(
* 'https://instance.example.com',
* axiosInstance,
* true,
* () => localStorage.getItem('token'),
* 'Bearer'
* );
*
* // Create a document
* const newDoc = await db.createDoc('Task', {
* subject: 'New Task',
* status: 'Open'
* });
*
* // Update a document
* await db.updateDoc('Task', newDoc.name, {
* status: 'Completed'
* });
* ```
*/
export declare class FrappeDB {
/** URL of the Frappe App instance */
private readonly appURL;
/** Axios instance for making HTTP requests */
readonly axios: AxiosInstance;
/** Whether to use token based authentication */
readonly useToken: boolean;
/** Function that returns the authentication token */
readonly token?: () => string;
/** Type of token to be used for authentication */
readonly tokenType?: 'Bearer' | 'token';
/**
* Creates a new FrappeDB instance.
*
* @param appURL - Base URL of the Frappe instance
* @param axios - Configured Axios instance for making requests
* @param useToken - Whether to use token-based authentication
* @param token - Function that returns the authentication token
* @param tokenType - Type of token to use ('Bearer' or 'token')
*
* @example
* ```typescript
* const db = new FrappeDB(
* 'https://instance.example.com',
* axiosInstance,
* true,
* () => localStorage.getItem('token'),
* 'Bearer'
* );
* ```
*/
constructor(appURL: string, axios: AxiosInstance, useToken?: boolean, token?: () => string, tokenType?: 'Bearer' | 'token');
/**
* Retrieves a document from the database.
*
* @template T - Type of the document
* @param doctype - Name of the doctype
* @param docname - Name/ID of the document
* @returns Promise resolving to the document
* @throws {FrappeError} If document retrieval fails
*
* @example
* ```typescript
* // Get a user document
* const user = await db.getDoc<User>('User', 'administrator');
* // Get a task document
* const task = await db.getDoc('Task', 'TASK-001');
* ```
*/
getDoc<T = object>(doctype: string, docname?: string): Promise<FrappeDoc<T>>;
/**
* Retrieves a list of documents with filtering, sorting, and pagination.
*
* @template T - Type of the document
* @template K - Type for filter fields
* @param doctype - Name of the doctype
* @param args - Query arguments for filtering, sorting, and pagination
* @returns Promise resolving to an array of documents
* @throws {FrappeError} If document retrieval fails
*
* @example
* ```typescript
* // Get all open tasks
* const tasks = await db.getDocList('Task', {
* filters: [['status', '=', 'Open']],
* orderBy: { field: 'creation', order: 'desc' },
* limit: 10
* });
*
* // Get specific user fields
* const users = await db.getDocList<User>('User', {
* fields: ['name', 'email', 'first_name'],
* filters: [['user_type', '=', 'System User']]
* });
* ```
*/
getDocList<T = object, K = FrappeDoc<T>>(doctype: string, args?: GetDocListArgs<K>): Promise<FrappeDoc<T>[]>;
/**
* Creates a new document in the database.
*
* @template T - Type of the document
* @param doctype - Name of the doctype
* @param value - Document data to create
* @returns Promise resolving to the created document
* @throws {FrappeError} If document creation fails
*
* @example
* ```typescript
* // Create a new task
* const task = await db.createDoc('Task', {
* subject: 'New Task',
* description: 'Task description',
* status: 'Open'
* });
*
* // Create a user
* const user = await db.createDoc<User>('User', {
* email: 'john@example.com',
* first_name: 'John',
* user_type: 'System User'
* });
* ```
*/
createDoc<T = object>(doctype: string, value: T): Promise<FrappeDoc<T>>;
/**
* Updates an existing document in the database.
*
* @template T - Type of the document
* @param doctype - Name of the doctype
* @param docname - Name/ID of the document to update
* @param value - Partial document data to update
* @returns Promise resolving to the updated document
* @throws {FrappeError} If document update fails
*
* @example
* ```typescript
* // Update task status
* await db.updateDoc('Task', 'TASK-001', {
* status: 'Completed',
* completion_date: new Date()
* });
*
* // Update user settings
* await db.updateDoc<User>('User', 'john@example.com', {
* language: 'en',
* time_zone: 'UTC'
* });
* ```
*/
updateDoc<T = object>(doctype: string, docname: string | null, value: Partial<T>): Promise<FrappeDoc<T>>;
/**
* Deletes a document from the database.
*
* @param doctype - Name of the doctype
* @param docname - Name/ID of the document to delete
* @returns Promise resolving to a success message
* @throws {FrappeError} If document deletion fails
*
* @example
* ```typescript
* // Delete a task
* await db.deleteDoc('Task', 'TASK-001');
*
* // Delete a user
* await db.deleteDoc('User', 'john@example.com');
* ```
*/
deleteDoc(doctype: string, docname?: string | null): Promise<{
message: string;
}>;
/**
* Gets the count of documents matching the specified filters.
*
* @template T - Type of the document for filter fields
* @param doctype - Name of the doctype
* @param filters - Optional filters to apply
* @param cache - Whether to cache the result
* @param debug - Whether to enable debug mode
* @returns Promise resolving to the count
* @throws {FrappeError} If count retrieval fails
*
* @example
* ```typescript
* // Count all open tasks
* const openTasks = await db.getCount('Task', [
* ['status', '=', 'Open']
* ]);
*
* // Count with caching
* const userCount = await db.getCount('User',
* [['user_type', '=', 'System User']],
* true
* );
* ```
*/
getCount<T = object>(doctype: string, filters?: Filter<T>[], cache?: boolean, debug?: boolean): Promise<number>;
/**
* Gets the most recent document of a doctype matching the specified criteria.
*
* @template T - Type of the document
* @param doctype - Name of the doctype
* @param args - Optional query arguments
* @returns Promise resolving to the last document
* @throws {FrappeError} If document retrieval fails
*
* @example
* ```typescript
* // Get last created task
* const lastTask = await db.getLastDoc('Task');
*
* // Get last completed task
* const lastCompleted = await db.getLastDoc('Task', {
* filters: [['status', '=', 'Completed']],
* orderBy: { field: 'modified', order: 'desc' }
* });
* ```
*/
getLastDoc<T = object>(doctype: string, args?: GetLastDocArgs<FrappeDoc<T>>): Promise<FrappeDoc<T>>;
}