@mussnad/frappe-js-client
Version:
Next-generation TS/JS client for Frappe REST APIs, built on axios for robust, type-safe integration.
370 lines (369 loc) • 14.3 kB
JavaScript
;
/**
* @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' }
* });
* ```
*/
var __assign = (this && this.__assign) || function () {
__assign = Object.assign || function(t) {
for (var s, i = 1, n = arguments.length; i < n; i++) {
s = arguments[i];
for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
t[p] = s[p];
}
return t;
};
return __assign.apply(this, arguments);
};
var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
return new (P || (P = Promise))(function (resolve, reject) {
function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
step((generator = generator.apply(thisArg, _arguments || [])).next());
});
};
var __generator = (this && this.__generator) || function (thisArg, body) {
var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
function verb(n) { return function (v) { return step([n, v]); }; }
function step(op) {
if (f) throw new TypeError("Generator is already executing.");
while (g && (g = 0, op[0] && (_ = 0)), _) try {
if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
if (y = 0, t) op = [op[0] & 2, t.value];
switch (op[0]) {
case 0: case 1: t = op; break;
case 4: _.label++; return { value: op[1], done: false };
case 5: _.label++; y = op[1]; op = [0]; continue;
case 7: op = _.ops.pop(); _.trys.pop(); continue;
default:
if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
if (t[2]) _.ops.pop();
_.trys.pop(); continue;
}
op = body.call(thisArg, _);
} catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
}
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.FrappeDB = void 0;
var axios_1 = require("../utils/axios");
/**
* 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'
* });
* ```
*/
var FrappeDB = /** @class */ (function () {
/**
* 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'
* );
* ```
*/
function FrappeDB(appURL, axios, useToken, token, tokenType) {
this.appURL = appURL;
this.axios = axios;
this.useToken = useToken !== null && useToken !== void 0 ? useToken : false;
this.token = token;
this.tokenType = tokenType;
}
/**
* 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');
* ```
*/
FrappeDB.prototype.getDoc = function (doctype, docname) {
if (docname === void 0) { docname = ''; }
return (0, axios_1.handleRequest)({
axios: this.axios,
config: {
method: 'GET',
url: "/api/resource/".concat(doctype, "/").concat(encodeURIComponent(docname)),
},
errorMessage: 'There was an error while fetching the document.',
transformResponse: function (response) { return response.data; },
});
};
/**
* 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']]
* });
* ```
*/
FrappeDB.prototype.getDocList = function (doctype, args) {
var _a;
var params = {};
if (args) {
var fields = args.fields, filters = args.filters, groupBy = args.groupBy, orderBy = args.orderBy, limit_start = args.limit_start, limit = args.limit, _b = args.asDict, asDict = _b === void 0 ? true : _b, orFilters = args.orFilters;
var orderByString = orderBy ? "".concat(String(orderBy === null || orderBy === void 0 ? void 0 : orderBy.field), " ").concat((_a = orderBy === null || orderBy === void 0 ? void 0 : orderBy.order) !== null && _a !== void 0 ? _a : 'asc') : '';
params = {
fields: fields ? JSON.stringify(fields) : undefined,
filters: filters ? JSON.stringify(filters) : undefined,
group_by: groupBy,
order_by: orderByString,
limit_start: limit_start,
limit: limit,
as_dict: asDict,
or_filters: orFilters ? JSON.stringify(orFilters) : undefined,
};
}
return (0, axios_1.handleRequest)({
axios: this.axios,
config: {
method: 'GET',
url: "/api/resource/".concat(doctype),
params: params,
},
errorMessage: 'There was an error while fetching the documents.',
transformResponse: function (response) { return response.data; },
});
};
/**
* 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'
* });
* ```
*/
FrappeDB.prototype.createDoc = function (doctype, value) {
return (0, axios_1.handleRequest)({
axios: this.axios,
config: {
method: 'POST',
url: "/api/resource/".concat(doctype),
data: value,
},
errorMessage: 'There was an error while creating the document.',
transformResponse: function (response) { return response.data; },
});
};
/**
* 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'
* });
* ```
*/
FrappeDB.prototype.updateDoc = function (doctype, docname, value) {
return (0, axios_1.handleRequest)({
axios: this.axios,
config: {
method: 'PUT',
url: "/api/resource/".concat(doctype, "/").concat(docname ? encodeURIComponent(docname) : docname),
data: value,
},
errorMessage: 'There was an error while updating the document.',
transformResponse: function (response) { return response.data; },
});
};
/**
* 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');
* ```
*/
FrappeDB.prototype.deleteDoc = function (doctype, docname) {
return (0, axios_1.handleRequest)({
axios: this.axios,
config: {
method: 'DELETE',
url: "/api/resource/".concat(doctype, "/").concat(docname ? encodeURIComponent(docname) : docname),
},
errorMessage: 'There was an error while deleting the document.',
transformResponse: function (response) { return response.data; },
});
};
/**
* 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' }
* });
* ```
*/
FrappeDB.prototype.getLastDoc = function (doctype, args) {
return __awaiter(this, void 0, void 0, function () {
var queryArgs, getDocLists;
return __generator(this, function (_a) {
switch (_a.label) {
case 0:
queryArgs = {
orderBy: {
field: 'creation',
order: 'desc',
},
};
if (args) {
queryArgs = __assign(__assign({}, queryArgs), args);
}
return [4 /*yield*/, this.getDocList(doctype, __assign(__assign({}, queryArgs), { limit: 1, fields: ['name'] }))];
case 1:
getDocLists = _a.sent();
if (getDocLists.length > 0) {
return [2 /*return*/, this.getDoc(doctype, getDocLists[0].name)];
}
return [2 /*return*/, {}];
}
});
});
};
return FrappeDB;
}());
exports.FrappeDB = FrappeDB;