sfobjects-basic-client 1.1.3 → 1.1.5

package/dist/index.d.ts

@@ -74,6 +74,13 @@ type MandatoryCreateProps<O> = {
         -readonly [P in K]: O[P];
     }, K>) : never) : never;
 }[KeyOf<O>];
+type UpdateableProps<O> = {
+    [K in keyof O]: NonNullable<O[K]> extends SfPrimitiveType ? (IsMutable<{
+        [P in K]: O[P];
+    }, {
+        -readonly [P in K]: O[P];
+    }, K>) : never;
+}[KeyOf<O>];
 export type SfRootSelect<OI, N extends KeyOf<OI>> = SfSelect<GetObjectTypes<OI>, OI[N]>;
 export type SfRootWhere<OI, N extends KeyOf<OI>> = SfWhere<GetObjectTypes<OI>, OI[N]>;
 export type SfRootOrderBy<OI, N extends KeyOf<OI>> = SfOrderBy<GetObjectTypes<OI>, OI[N]>;
@@ -88,7 +95,9 @@ export type SfUpsert<O, K extends MandatoryCreateProps<O>> = SfCreate<O> & {
 };
 export type SfUpdate<O> = {
     Id: string;
-} & SfCreate<O>;
+} & {
+    [K in UpdateableProps<O>]+?: O[K];
+};
 export type SfObjCfg = {
     objectPrefix: string;
     dateTypes: string[];
@@ -124,6 +133,11 @@ export type SfDmlOptions = {
         };
     };
 };
+export type SfClientOptions = {
+    breakOnError?: boolean;
+    query?: SfQueryOptions;
+    dml?: SfDmlOptions;
+};
 export type SfQueryResult<R> = {
     records: R[];
 };
@@ -159,6 +173,7 @@ export interface SfWhereActions<OI, N extends KeyOf<OI>, S extends SfRootSelect<
 }
 export interface SfSelectAditionalActions<OI, N extends KeyOf<OI>, S extends SfRootSelect<OI, N>> {
     find: (id: string, options?: SfQueryOptions) => Promise<SfRootSelectProjection<OI, N, S> | undefined>;
+    retrieve: (id: string, options?: SfQueryOptions) => Promise<SfRootSelectProjection<OI, N, S>>;
     selection: S[];
 }
 export interface SfObjActions<OI, N extends KeyOf<OI>> {
@@ -174,10 +189,14 @@ export interface SfObjActions<OI, N extends KeyOf<OI>> {
     upsert: <K extends MandatoryCreateProps<OI[N]>>(records: SfUpsert<OI[N], K>[], key: K, options?: SfDmlOptions) => PromiseLike<SfSaveResult[]>;
     select: <S extends SfRootSelect<OI, N>>(select: S[]) => (SfSelectActions<OI, N, S> & SfWhereActions<OI, N, S> & SfSelectAditionalActions<OI, N, S>);
 }
+export declare class SfBasicClientError extends Error {
+    errors: SfSaveError[];
+    constructor(errors: SfSaveError[]);
+}
 export declare function isPlainObject(value: unknown): value is Record<string, any>;
 export declare function constructSoql<OI>(_cfg: SfObjCfgIndex<OI>): (objName: string, from: string, select: (string | {})[], where?: string | Record<string, any>, orderBy?: Record<string, any>, limit?: number) => string;
-export declare function getSfObject<OI>(_cfg: SfObjCfgIndex<OI>): <N extends KeyOf<OI>>(from: N, _conn: ISfConnection) => SfObjActions<OI, N>;
-export declare const getSfObjects: <OI>(cfg: SfObjCfgIndex<OI>) => (conn: ISfConnection) => { [N in KeyOf<OI>]: SfObjActions<OI, N>; };
+export declare function getSfObject<OI>(_cfg: SfObjCfgIndex<OI>, o?: SfClientOptions): <N extends KeyOf<OI>>(from: N, _conn: ISfConnection) => SfObjActions<OI, N>;
+export declare const getSfObjects: <OI>(cfg: SfObjCfgIndex<OI>) => (conn: ISfConnection, options?: SfClientOptions) => { [N in KeyOf<OI>]: SfObjActions<OI, N>; };
 export declare const sfObject: <OI, N extends KeyOf<OI>>(cfg: SfObjCfgIndex<OI>, n: N) => {
     info: SfObjCfgIndex<OI>[N];
     select: <S extends SfRootSelect<OI, N>>(s: S[]) => S[];

package/dist/index.js

@@ -21,7 +21,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sfObject = exports.getSfObjects = void 0;
+exports.sfObject = exports.getSfObjects = exports.SfBasicClientError = void 0;
 exports.isPlainObject = isPlainObject;
 exports.constructSoql = constructSoql;
 exports.getSfObject = getSfObject;
@@ -70,6 +70,15 @@ const OP_RULES = [
     { ops: OP_KEYS_LIKE, soqlOp: 'like' },
     { ops: OP_KEYS_NLIKE, soqlOp: 'like', isNot: true },
 ];
+class SfBasicClientError extends Error {
+    constructor(errors) {
+        super('Salesforce error(s): ' + errors.map(e => { var _a; return `[${e.errorCode}] ${e.message}, field(s): ${(_a = e.fields) === null || _a === void 0 ? void 0 : _a.join(',')}`; }).join(';\r\n'));
+        this.errors = errors;
+        this.name = 'SfBasicClientError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.SfBasicClientError = SfBasicClientError;
 // functions
 function isPlainObject(value) {
     if (typeof value !== 'object' || value === null)
@@ -222,36 +231,54 @@ function constructSoql(_cfg) {
     }
     return _constructFullQuery;
 }
-function getSfObject(_cfg) {
+function processSaveResult(sr, breakOnError) {
+    if (breakOnError) {
+        const _errors = sr.filter(r => (r.success !== true)).map(r => r.errors).flat();
+        if (_errors.length) {
+            throw new SfBasicClientError(_errors);
+        }
+    }
+    return sr;
+}
+function getSfObject(_cfg, o) {
     function _query(conn, from, select, where, orderBy, limit) {
         const soql = () => constructSoql(_cfg)(from, from, select, where, orderBy, limit);
         return ({
             soql,
-            get: (options) => __awaiter(this, void 0, void 0, function* () { return yield conn.query(soql(), options); }), // to get rid of promiselike,            
+            get: (...args_1) => __awaiter(this, [...args_1], void 0, function* (options = o === null || o === void 0 ? void 0 : o.query) { return yield conn.query(soql(), options); }), // to get rid of promiselike,            
             limit: (limit) => _query(conn, from, select, where, orderBy, limit)
         });
     }
+    function _queryOne(conn, from, select, id, options = o === null || o === void 0 ? void 0 : o.query) {
+        return _query(conn, from, select, `Id = '${id}'`).limit(1).get(options);
+    }
     return (from, _conn) => {
         return ({
             query: (q) => {
                 const { select, where, orderBy, limit } = q;
                 return _query(_conn, from, select, where, orderBy, limit);
             },
-            delete: (ids, options) => _conn.delete(from, ids, options),
-            update: (records, options) => _conn.update(from, records, options),
-            create: (records, options) => _conn.create(from, records, options),
-            upsert: (records, key, options) => _conn.upsert(from, records, key, options),
-            select: (select) => (Object.assign(Object.assign({}, _query(_conn, from, select)), { orderBy: (orderBy) => _query(_conn, from, select, undefined, orderBy), where: (where) => (Object.assign(Object.assign({}, _query(_conn, from, select, where)), { orderBy: (orderBy) => _query(_conn, from, select, where, orderBy) })), find: (id, options) => __awaiter(this, void 0, void 0, function* () {
-                    const result = yield _query(_conn, from, select, `Id = '${id}'`).limit(1).get(options);
+            delete: (ids_1, ...args_1) => __awaiter(this, [ids_1, ...args_1], void 0, function* (ids, options = o === null || o === void 0 ? void 0 : o.dml) { return processSaveResult(yield _conn.delete(from, ids, options), o === null || o === void 0 ? void 0 : o.breakOnError); }),
+            update: (records_1, ...args_1) => __awaiter(this, [records_1, ...args_1], void 0, function* (records, options = o === null || o === void 0 ? void 0 : o.dml) { return processSaveResult(yield _conn.update(from, records, options), o === null || o === void 0 ? void 0 : o.breakOnError); }),
+            create: (records_1, ...args_1) => __awaiter(this, [records_1, ...args_1], void 0, function* (records, options = o === null || o === void 0 ? void 0 : o.dml) { return processSaveResult(yield _conn.create(from, records, options), o === null || o === void 0 ? void 0 : o.breakOnError); }),
+            upsert: (records_1, key_1, ...args_1) => __awaiter(this, [records_1, key_1, ...args_1], void 0, function* (records, key, options = o === null || o === void 0 ? void 0 : o.dml) { return processSaveResult(yield _conn.upsert(from, records, key, options), o === null || o === void 0 ? void 0 : o.breakOnError); }),
+            select: (select) => (Object.assign(Object.assign({}, _query(_conn, from, select)), { orderBy: (orderBy) => _query(_conn, from, select, undefined, orderBy), where: (where) => (Object.assign(Object.assign({}, _query(_conn, from, select, where)), { orderBy: (orderBy) => _query(_conn, from, select, where, orderBy) })), find: (id_1, ...args_1) => __awaiter(this, [id_1, ...args_1], void 0, function* (id, options = o === null || o === void 0 ? void 0 : o.query) {
+                    const result = yield _queryOne(_conn, from, select, id, options);
                     if (result.records.length) {
                         return result.records[0];
                     }
+                }), retrieve: (id_1, ...args_1) => __awaiter(this, [id_1, ...args_1], void 0, function* (id, options = o === null || o === void 0 ? void 0 : o.query) {
+                    const result = yield _queryOne(_conn, from, select, id, options);
+                    if (!result.records.length) {
+                        throw new Error(`Record with id '${id}' is not found in '${from}'.`);
+                    }
+                    return result.records[0];
                 }), selection: select }))
         });
     };
 }
-const getSfObjects = (cfg) => (conn) => {
-    const _func = getSfObject(cfg);
+const getSfObjects = (cfg) => (conn, options) => {
+    const _func = getSfObject(cfg, options);
     return Object.keys(cfg).reduce((p, n) => (Object.assign(Object.assign({}, p), { [n]: _func(n, conn) })), {});
 };
 exports.getSfObjects = getSfObjects;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfobjects-basic-client",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Basic Salesforce Client to use together with sfobjects-to-typescript lib",
   "license": "ISC",
   "author": "Murad Aliyev",  

package/src/index.ts

@@ -149,6 +149,16 @@ type MandatoryCreateProps<O> = {
 }[KeyOf<O>];
 
 
+// Update
+
+type UpdateableProps<O> = {
+    [K in keyof O]: NonNullable<O[K]> extends SfPrimitiveType ? (
+        IsMutable<{ [P in K]: O[P] }, { -readonly [P in K]: O[P] }, K>
+    ) : never
+
+}[KeyOf<O>];
+
+
 
 // Select
 
@@ -169,11 +179,11 @@ export type SfCreate<O> = { [K in MandatoryCreateProps<O>]: O[K] } & { [K in Opt
 
 // Upsert
 
-export type SfUpsert<O, K extends MandatoryCreateProps<O>> = SfCreate<O> & { [P in K]: O[P] };
+export type SfUpsert<O, K extends MandatoryCreateProps<O>/* external keys */> = SfCreate<O> & { [P in K]: O[P] };
 
 // Update
 
-export type SfUpdate<O> = { Id: string } & SfCreate<O>;
+export type SfUpdate<O> = { Id: string } & { [K in UpdateableProps<O>]+?: O[K] };
 
 
 // Basic Client
@@ -218,6 +228,12 @@ export type SfDmlOptions = {
     };
 };
 
+export type SfClientOptions = {
+    breakOnError?: boolean
+    query?: SfQueryOptions;
+    dml?: SfDmlOptions;
+}
+
 export type SfQueryResult<R> = { records: R[] };
 
 export type SfSaveResult = {
@@ -258,6 +274,7 @@ export interface SfWhereActions<OI, N extends KeyOf<OI>, S extends SfRootSelect<
 
 export interface SfSelectAditionalActions<OI, N extends KeyOf<OI>, S extends SfRootSelect<OI, N>> {
     find: (id: string, options?: SfQueryOptions) => Promise<SfRootSelectProjection<OI, N, S> | undefined>;
+    retrieve: (id: string, options?: SfQueryOptions) => Promise<SfRootSelectProjection<OI, N, S>>;
     selection: S[];
     //S extends SfRootSelect<OI, N>
 }
@@ -271,6 +288,22 @@ export interface SfObjActions<OI, N extends KeyOf<OI>> {
     select: <S extends SfRootSelect<OI, N>>(select: S[]) => (SfSelectActions<OI, N, S> & SfWhereActions<OI, N, S> & SfSelectAditionalActions<OI, N, S>);
 }
 
+export class SfBasicClientSaveError extends Error {
+    constructor(public errors: SfSaveError[]) {
+        super('Salesforce error(s): ' + errors.map(e => `[${e.errorCode}] ${e.message}, field(s): ${e.fields?.join(',')}`).join(';\r\n'))
+        this.name = 'SfBasicClientSaveError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+export class SfBasicClientReadError extends Error {
+    constructor(public error: string) {
+        super('Salesforce error: ' + error)
+        this.name = 'SfBasicClientReadError';
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
 // functions
 
 export function isPlainObject(value: unknown): value is Record<string, any> {
@@ -340,8 +373,6 @@ export function constructSoql<OI>(_cfg: SfObjCfgIndex<OI>) {
             'limit': limit?.toString()
         }
 
-
-
         return Object.keys(o).filter(k => !!o[k]).reduce((p, k) => ([p, k, o[k]].join(' ')), '');
     }
 
@@ -509,7 +540,22 @@ export function constructSoql<OI>(_cfg: SfObjCfgIndex<OI>) {
     return _constructFullQuery;
 }
 
-export function getSfObject<OI>(_cfg: SfObjCfgIndex<OI>) {
+function processSaveResult(sr: SfSaveResult[], breakOnError?: boolean): SfSaveResult[] {
+
+    if (breakOnError) {
+
+        const _errors: SfSaveError[] = sr.filter(r => (r.success !== true)).map(r => r.errors).flat();
+
+        if (_errors.length) {
+            throw new SfBasicClientSaveError(_errors);
+        }
+    }
+
+    return sr;
+}
+
+export function getSfObject<OI>(_cfg: SfObjCfgIndex<OI>, o?: SfClientOptions) {
+
 
     function _query<S extends SfRootSelect<OI, N>, N extends KeyOf<OI>>(
         conn: ISfConnection,
@@ -524,11 +570,21 @@ export function getSfObject<OI>(_cfg: SfObjCfgIndex<OI>) {
 
         return ({
             soql,
-            get: async (options?: SfQueryOptions) => await conn.query<SfRootSelectProjection<OI, N, S>>(soql(), options), // to get rid of promiselike,            
+            get: async (options: SfQueryOptions | undefined = o?.query) => await conn.query<SfRootSelectProjection<OI, N, S>>(soql(), options), // to get rid of promiselike,            
             limit: (limit: number) => _query(conn, from, select, where, orderBy, limit)
         });
     }
 
+    function _queryOne<S extends SfRootSelect<OI, N>, N extends KeyOf<OI>>(
+        conn: ISfConnection,
+        from: N,
+        select: S[],
+        id: string,
+        options: SfQueryOptions | undefined = o?.query
+    ) {
+        return _query(conn, from, select, `Id = '${id}'`).limit(1).get(options);
+    }
+
     return <N extends KeyOf<OI>>(from: N, _conn: ISfConnection): SfObjActions<OI, N> => {
 
         return ({
@@ -538,13 +594,13 @@ export function getSfObject<OI>(_cfg: SfObjCfgIndex<OI>) {
                 return _query(_conn, from, select, where, orderBy, limit);
             },
 
-            delete: (ids: string[], options?: SfDmlOptions) => _conn.delete(from, ids, options),
+            delete: async (ids: string[], options: SfDmlOptions | undefined = o?.dml) => processSaveResult(await _conn.delete(from, ids, options), o?.breakOnError),
 
-            update: (records: SfUpdate<OI[N]>[], options?: SfDmlOptions) => _conn.update(from, records, options),
+            update: async (records: SfUpdate<OI[N]>[], options: SfDmlOptions | undefined = o?.dml) => processSaveResult(await _conn.update(from, records, options), o?.breakOnError),
 
-            create: (records: SfCreate<OI[N]>[], options?: SfDmlOptions) => _conn.create(from, records, options),
+            create: async (records: SfCreate<OI[N]>[], options: SfDmlOptions | undefined = o?.dml) => processSaveResult(await _conn.create(from, records, options), o?.breakOnError),
 
-            upsert: <K extends MandatoryCreateProps<OI[N]>>(records: SfUpsert<OI[N], K>[], key: K, options?: SfDmlOptions) => _conn.upsert(from, records, key, options),
+            upsert: async <K extends MandatoryCreateProps<OI[N]>>(records: SfUpsert<OI[N], K>[], key: K, options: SfDmlOptions | undefined = o?.dml) => processSaveResult(await _conn.upsert(from, records, key, options), o?.breakOnError),
 
             select: <S extends SfRootSelect<OI, N>>(select: S[]) => ({
 
@@ -560,17 +616,27 @@ export function getSfObject<OI>(_cfg: SfObjCfgIndex<OI>) {
 
                 }),
 
-                find: async (id: string, options?: SfQueryOptions) => {
+                find: async (id: string, options: SfQueryOptions | undefined = o?.query) => {
 
-                    const result = await _query(_conn, from, select, `Id = '${id}'`).limit(1).get(options);
+                    const result = await _queryOne(_conn, from, select, id, options);
 
                     if (result.records.length) {
                         return result.records[0];
                     }
                 },
 
-                selection: select
+                retrieve: async (id: string, options: SfQueryOptions | undefined = o?.query) => {
 
+                    const result = await _queryOne(_conn, from, select, id, options);
+
+                    if (!result.records.length) {
+                        throw new SfBasicClientReadError(`Record with id '${id}' is not found in '${from}'.`);
+                    }
+
+                    return result.records[0];
+                },
+
+                selection: select
             })
         })
     };
@@ -578,8 +644,8 @@ export function getSfObject<OI>(_cfg: SfObjCfgIndex<OI>) {
 }
 
 
-export const getSfObjects = <OI>(cfg: SfObjCfgIndex<OI>) => (conn: ISfConnection) => {
-    const _func = getSfObject<OI>(cfg);
+export const getSfObjects = <OI>(cfg: SfObjCfgIndex<OI>) => (conn: ISfConnection, options?: SfClientOptions) => {
+    const _func = getSfObject<OI>(cfg, options);
     return (Object.keys(cfg) as KeyOf<OI>[]).reduce((p, n) => ({ ...p, [n]: _func(n, conn) }), {} as { [N in KeyOf<OI>]: SfObjActions<OI, N> });
 }