pinejs-client-fetch 1.0.2 → 1.0.3

package/build/index.umd.js

@@ -38,9 +38,11 @@
 	Object.defineProperty(exports, "__esModule", { value: true });
 	exports.PinejsClientCore = void 0;
 	function isArray(value) {
+	    // See: https://github.com/microsoft/TypeScript/issues/17002
 	    return Array.isArray(value);
 	}
 	const noop = () => {
+	    // noop
 	};
 	const deprecated = (() => {
 	    const deprecationMessages = {
@@ -50,6 +52,14 @@
 	        countWithNestedOperationInFilter: "'`$filter: { a: { $count: { $op: number } } }` is deprecated, please use `$filter: { $eq: [ { a: { $count: {} } }, number ] }` instead.",
 	        countInOrderBy: "'`$orderby: 'a/$count'` is deprecated, please use `$orderby: { a: { $count: {...} } }` instead.",
 	        non$filterOptionIn$expand$count: 'using OData options other than $filter in a `$expand: { a: { $count: {...} } }` is deprecated, please remove them.',
+	        urlInGetOrCreate: 'Passing `url` to `getOrCreate` is deprecated as it is unsupported and may have adverse effects, please use a query object instead.',
+	        urlInUpsert: 'Passing `url` to `upsert` is deprecated as it is unsupported and may have adverse effects, please use a query object instead.',
+	        urlInCompile: 'Passing `url` to `compile` is deprecated, please use a query object instead or use `request` directly.',
+	        urlInGet: 'Passing `url` to `get` is deprecated, please use a query object instead or use `request` directly.',
+	        urlInPost: 'Passing `url` to `post` is deprecated, please use a query object instead or use `request` directly.',
+	        urlInPatch: 'Passing `url` to `patch` is deprecated, please use a query object instead or use `request` directly.',
+	        urlInPut: 'Passing `url` to `put` is deprecated, please use a query object instead or use `request` directly.',
+	        urlInDelete: 'Passing `url` to `delete` is deprecated, please use a query object instead or use `request` directly.',
 	    };
 	    const result = {};
 	    for (const key of Object.keys(deprecationMessages)) {
@@ -114,6 +124,9 @@
 	                    return;
 	                }
 	                this.restartTimeout();
+	                // Catch errors in event subscribers so that they don't trigger
+	                // the 'catch' below, and that subsequent subscribers will still
+	                // be called
 	                this.subscribers.data.forEach((fn) => {
 	                    try {
 	                        fn(response);
@@ -179,6 +192,7 @@
 	        isBoolean(value) ||
 	        isDate(value));
 	};
+	// Escape a resource name (string), or resource path (array)
 	const escapeResource = (resource) => {
 	    if (isString(resource)) {
 	        resource = encodeURIComponent(resource);
@@ -191,6 +205,7 @@
 	    }
 	    return resource.replace(trailingCountRegex, '/$count');
 	};
+	// Escape a primitive value
 	const escapeValue = (value) => {
 	    if (isString(value)) {
 	        value = value.replace(/'/g, "''");
@@ -223,6 +238,7 @@
 	        throw new Error('Expected a string or array, got: ' + typeof strOrArray);
 	    }
 	};
+	// Join together a bunch of statements making sure the whole lot is correctly parenthesised
 	const bracketJoin = (arr, separator) => {
 	    if (arr.length === 1) {
 	        return arr[0];
@@ -243,6 +259,7 @@
 	    });
 	    return resultArr;
 	};
+	// Add the parentKey + operator if it exists.
 	const addParentKey = (filter, parentKey, operator = ' eq ') => {
 	    if (parentKey != null) {
 	        if (isArray(filter)) {
@@ -267,6 +284,7 @@
 	    for (const index of Object.keys(params)) {
 	        const param = params[index];
 	        let paramStr = `(${buildFilter(param).join('')})`;
+	        // Escape $ for filter.replace
 	        paramStr = paramStr.replace(/\$/g, '$$$$');
 	        filter = filter.replace(new RegExp(`\\$${index}([^a-zA-Z0-9]|$)`, 'g'), `${paramStr}$1`);
 	    }
@@ -327,6 +345,7 @@
 	        throw new Error(`Expected null/string/number/obj/array, got: ${typeof filter}`);
 	    }
 	};
+	// Handle special cases for all the different $ operators.
 	const handleFilterOperator = (filter, operator, parentKey) => {
 	    switch (operator) {
 	        case '$ne':
@@ -341,6 +360,7 @@
 	        case '$div':
 	        case '$mod':
 	            return filterOperation(filter, operator, parentKey);
+	        // break
 	        case '$contains':
 	        case '$endswith':
 	        case '$startswith':
@@ -397,12 +417,14 @@
 	            }
 	            return addParentKey(`duration'${durationString}'`, parentKey);
 	        }
+	        // break
 	        case '$raw': {
 	            const filterx = filter;
 	            if (isString(filterx)) {
 	                return addParentKey(`(${filterx})`, parentKey);
 	            }
 	            else if (!isPrimitive(filterx)) {
+	                // This needs to use the mutable version `Array.isArray` or otherwise the destructuring gets the wrong types?
 	                if (Array.isArray(filterx)) {
 	                    const [rawFilter, ...params] = filterx;
 	                    if (!isString(rawFilter)) {
@@ -433,6 +455,7 @@
 	            }
 	            throw new Error(`Expected string/array/object for ${operator}, got: ${typeof filterx}`);
 	        }
+	        // break
 	        case '$': {
 	            const resource = escapeResource(filter);
 	            return addParentKey(resource, parentKey);
@@ -441,6 +464,7 @@
 	            let keys = ['$count'];
 	            if (parentKey != null &&
 	                isObject(filter) &&
+	                // Handles the `$filter: $op: [ {a: {$count: {'...'}}}, value]`` case.
 	                (Object.keys(filter).length === 0 ||
 	                    Object.prototype.hasOwnProperty.call(filter, '$filter'))) {
 	                keys = parentKey.slice(0, parentKey.length - 1);
@@ -450,14 +474,17 @@
 	            if (parentKey != null) {
 	                keys = parentKey.concat(keys);
 	            }
+	            // Handles the `$filter: a: $count: value` case.
 	            deprecated.countWithNestedOperationInFilter();
 	            return buildFilter(filter, keys);
 	        }
+	        // break
 	        case '$and':
 	        case '$or': {
 	            const filterStr = buildFilter(filter, undefined, ` ${operator.slice(1)} `);
 	            return addParentKey(filterStr, parentKey);
 	        }
+	        // break
 	        case '$in': {
 	            filter = filter;
 	            if (isPrimitive(filter)) {
@@ -486,21 +513,24 @@
 	                throw new Error(`Expected null/string/number/bool/obj/array, got: ${typeof filter}`);
 	            }
 	        }
+	        // break
 	        case '$not': {
 	            const filterStr = `not(${buildFilter(filter).join('')})`;
 	            return addParentKey(filterStr, parentKey);
 	        }
+	        // break
 	        case '$any':
 	        case '$all': {
-	            filter = filter;
-	            const alias = filter.$alias;
-	            const expr = filter.$expr;
+	            const filterx = filter;
+	            const alias = filterx.$alias;
+	            const expr = filterx.$expr;
 	            if (alias == null) {
 	                throw new Error(`Lambda expression (${operator}) has no alias defined.`);
 	            }
 	            if (expr == null) {
 	                throw new Error(`Lambda expression (${operator}) has no expr defined.`);
 	            }
+	            // Disable the expandFilter deprecation notice when inside a lambda expr
 	            const deprecatedFn = (deprecated.expandFilter = noop);
 	            let filterStr;
 	            try {
@@ -512,6 +542,7 @@
 	            filterStr = `${operator.slice(1)}(${alias}:${filterStr})`;
 	            return addParentKey(filterStr, parentKey, '/');
 	        }
+	        // break
 	        default:
 	            throw new Error(`Unrecognised operator: '${operator}'`);
 	    }
@@ -521,10 +552,10 @@
 	        if (value === undefined) {
 	            throw new Error(`'${key}' was present on a filter object but undefined, did you mean to use null instead?`);
 	        }
-	        if (key[0] === '$') {
+	        if (key.startsWith('$')) {
 	            return handleFilterOperator(value, key, parentKey);
 	        }
-	        else if (key[0] === '@') {
+	        else if (key.startsWith('@')) {
 	            const parameterAlias = escapeParameterAlias(value);
 	            return addParentKey(parameterAlias, parentKey);
 	        }
@@ -548,6 +579,7 @@
 	        return buildFilter(value, parentKey);
 	    });
 	};
+	// Turn a filter query object into an OData $filter string
 	const buildFilter = (filter, parentKey, joinStr) => {
 	    if (isPrimitive(filter)) {
 	        const filterStr = escapeValue(filter);
@@ -586,10 +618,13 @@
 	        return join(result);
 	    }
 	    else if (isObject(orderby)) {
-	        const _a = orderby, { $dir } = _a, $orderby = __rest(_a, ["$dir"]);
+	        const { $dir } = orderby, $orderby = __rest(orderby, ["$dir"]);
 	        const result = mapObj($orderby, (dirOrOptions, key) => {
 	            let propertyPath = key;
 	            let dir = $dir;
+	            if (dirOrOptions == null) {
+	                throw new Error(`Orderby object values must not be null, got null for ${key}`);
+	            }
 	            if (typeof dirOrOptions === 'string') {
 	                dir = dirOrOptions;
 	            }
@@ -656,12 +691,14 @@
 	            break;
 	        }
 	        default:
-	            if (option[0] === '@') {
+	            // Escape parameter aliases as primitives
+	            if (option.startsWith('@')) {
 	                if (!isPrimitive(value)) {
 	                    throw new Error(`Unknown type for parameter alias option '${option}': ${typeof value}`);
 	                }
 	                compiledValue = '' + escapeValue(value);
 	            }
+	            // Unknown values are left as-is
 	            else if (isArray(value)) {
 	                compiledValue = join(value);
 	            }
@@ -685,8 +722,12 @@
 	        }
 	        options = options.$count;
 	        parentKey += '/$count';
+	        // Check whether there is anything else other than $filter in the $count
+	        // and error b/c it's invalid.
 	        if (Object.keys(options).length >
 	            (Object.prototype.hasOwnProperty.call(options, '$filter') ? 1 : 0)) {
+	            // TODO: Remove the optionOperation check in the next major,
+	            // so that it throws for all operators.
 	            if (optionOperation === '$expand') {
 	                deprecated.non$filterOptionIn$expand$count();
 	            }
@@ -696,7 +737,7 @@
 	        }
 	    }
 	    const optionsArray = mapObj(options, (value, key) => {
-	        if (key[0] === '$') {
+	        if (key.startsWith('$')) {
 	            if (!isValidOption(key)) {
 	                throw new Error(`Unknown key option '${key}'`);
 	            }
@@ -716,9 +757,12 @@
 	};
 	const handleExpandObject = (expand) => {
 	    const expands = mapObj(expand, (value, key) => {
-	        if (key[0] === '$') {
+	        if (key.startsWith('$')) {
 	            throw new Error('Cannot have expand options without first expanding something!');
 	        }
+	        if (value == null) {
+	            throw new Error(`Expand object values must not be null, got null for ${key}`);
+	        }
 	        if (isPrimitive(value)) {
 	            const jsonValue = JSON.stringify(value);
 	            throw new Error(`'$expand: ${key}: ${jsonValue}' is invalid, use '$expand: ${key}: $expand: ${jsonValue}' instead.`);
@@ -762,6 +806,7 @@
 	    if (typeof retryAfterRaw !== 'string') {
 	        return;
 	    }
+	    // TODO: Add support for parsing and converting HTTP date format values to delay.
 	    const retryAfterSeconds = parseInt(retryAfterRaw, 10);
 	    if (!Number.isInteger(retryAfterSeconds) || retryAfterSeconds < 0) {
 	        return;
@@ -775,6 +820,7 @@
 	    'retry',
 	];
 	class PinejsClientCore {
+	    // `backendParams` must be used by a backend for any additional parameters it may have.
 	    constructor(params) {
 	        this.apiPrefix = '/';
 	        this.passthrough = {};
@@ -799,11 +845,12 @@
 	    callWithRetry(fnCall, retry) {
 	        return __awaiter(this, void 0, void 0, function* () {
 	            var _a, _b, _c, _d, _e, _f, _g;
+	            // Explicitly passing retry as false disables retrying for this call.
 	            if (retry === false || (retry == null && this.retry === false)) {
 	                return yield fnCall();
 	            }
 	            const retryDefaultParameters = this.retry || {};
-	            const retryParameters = retry || {};
+	            const retryParameters = retry !== null && retry !== void 0 ? retry : {};
 	            const minDelayMs = (_a = retryParameters.minDelayMs) !== null && _a !== void 0 ? _a : retryDefaultParameters.minDelayMs;
 	            const maxDelayMs = (_b = retryParameters.maxDelayMs) !== null && _b !== void 0 ? _b : retryDefaultParameters.maxDelayMs;
 	            const maxAttempts = (_c = retryParameters.maxAttempts) !== null && _c !== void 0 ? _c : retryDefaultParameters.maxAttempts;
@@ -823,6 +870,7 @@
 	            const getRetryAfterHeader = (_e = retryParameters.getRetryAfterHeader) !== null && _e !== void 0 ? _e : retryDefaultParameters.getRetryAfterHeader;
 	            let attempt = 1;
 	            const canRetryHandler = (_g = (_f = retryParameters.canRetry) !== null && _f !== void 0 ? _f : retryDefaultParameters.canRetry) !== null && _g !== void 0 ? _g : this.canRetryDefaultHandler;
+	            // eslint-disable-next-line no-constant-condition -- we handle retry logic/delaying within the loop
 	            while (true) {
 	                try {
 	                    return yield fnCall();
@@ -832,6 +880,8 @@
 	                        throw err;
 	                    }
 	                    let delayMs = Math.min(Math.pow(2, (attempt - 1)) * minDelayMs, maxDelayMs);
+	                    // note that attempt is incremented before calling onRetryHandler because
+	                    // retries effectively begin with attempt number 2.
 	                    attempt++;
 	                    const retryAfterDelayMs = getRetryAfterHeaderDelayMs(getRetryAfterHeader, err);
 	                    if (retryAfterDelayMs != null && retryAfterDelayMs > delayMs) {
@@ -845,6 +895,7 @@
 	            }
 	        });
 	    }
+	    // `backendParams` must be used by a backend for any additional parameters it may have.
 	    clone(params, backendParams) {
 	        if (isString(params)) {
 	            params = { apiPrefix: params };
@@ -871,8 +922,8 @@
 	    }
 	    get(params) {
 	        return __awaiter(this, void 0, void 0, function* () {
-	            if (isString(params)) {
-	                throw new Error('`get(url)` is no longer supported, please use `get({ url })` instead.');
+	            if (params.url != null) {
+	                deprecated.urlInGet();
 	            }
 	            const result = yield this.request(Object.assign(Object.assign({}, params), { method: 'GET' }));
 	            return this._transformGetResult(params, result);
@@ -886,6 +937,7 @@
 	            throw new Error("Invalid response received, the 'd' property is missing.");
 	        }
 	        if (params.id != null) {
+	            // singular
 	            if (data.d.length > 1) {
 	                throw new Error('Returned multiple results when only one was expected.');
 	            }
@@ -905,32 +957,35 @@
 	        return new Poll(requestFn, pollInterval);
 	    }
 	    put(params) {
-	        if (isString(params)) {
-	            throw new Error('`put(url)` is no longer supported, please use `put({ url })` instead.');
+	        if (params.url != null) {
+	            deprecated.urlInPut();
 	        }
 	        return this.request(Object.assign(Object.assign({}, params), { method: 'PUT' }));
 	    }
 	    patch(params) {
-	        if (isString(params)) {
-	            throw new Error('`patch(url)` is no longer supported, please use `patch({ url })` instead.');
+	        if (params.url != null) {
+	            deprecated.urlInPatch();
 	        }
 	        return this.request(Object.assign(Object.assign({}, params), { method: 'PATCH' }));
 	    }
 	    post(params) {
-	        if (isString(params)) {
-	            throw new Error('`post(url)` is no longer supported, please use `post({ url })` instead.');
+	        if (params.url != null) {
+	            deprecated.urlInPost();
 	        }
 	        return this.request(Object.assign(Object.assign({}, params), { method: 'POST' }));
 	    }
 	    delete(params) {
-	        if (isString(params)) {
-	            throw new Error('`delete(url)` is no longer supported, please use `delete({ url })` instead.');
+	        if (params.url != null) {
+	            deprecated.urlInDelete();
 	        }
 	        params.method = 'DELETE';
 	        return this.request(Object.assign(Object.assign({}, params), { method: 'DELETE' }));
 	    }
 	    getOrCreate(params) {
 	        return __awaiter(this, void 0, void 0, function* () {
+	            if ('url' in params && params.url != null) {
+	                deprecated.urlInGetOrCreate();
+	            }
 	            const { id, body } = params, restParams = __rest(params, ["id", "body"]);
 	            if (params.resource.endsWith('/$count')) {
 	                throw new Error('getOrCreate does not support $count on resources');
@@ -950,6 +1005,9 @@
 	    }
 	    upsert(params) {
 	        return __awaiter(this, void 0, void 0, function* () {
+	            if ('url' in params && params.url != null) {
+	                deprecated.urlInUpsert();
+	            }
 	            const { id, body } = params, restParams = __rest(params, ["id", "body"]);
 	            if (!isObject(id)) {
 	                throw new Error('The id property must be an object');
@@ -978,11 +1036,13 @@
 	        });
 	    }
 	    prepare(params) {
+	        var _a;
 	        if (isString(params)) {
 	            throw new Error('`prepare(url)` is no longer supported, please use `prepare({ url })` instead.');
 	        }
-	        const compiledUrl = this.compile(params);
-	        const urlQueryParamsStr = compiledUrl.indexOf('?') === -1 ? '?' : '&';
+	        // precompile the URL string to improve performance
+	        const compiledUrl = (_a = params.url) !== null && _a !== void 0 ? _a : this.compile(params);
+	        const urlQueryParamsStr = !compiledUrl.includes('?') ? '?' : '&';
 	        if (params.method == null) {
 	            params.method = 'GET';
 	        }
@@ -1029,6 +1089,7 @@
 	            throw new Error('Params must be an object not a string');
 	        }
 	        if (params.url != null) {
+	            deprecated.urlInCompile();
 	            return params.url;
 	        }
 	        else {
@@ -1076,7 +1137,7 @@
 	            let queryOptions = [];
 	            if (options != null) {
 	                queryOptions = mapObj(options, (value, option) => {
-	                    if (option[0] === '$' && !isValidOption(option)) {
+	                    if (option.startsWith('$') && !isValidOption(option)) {
 	                        throw new Error(`Unknown odata option '${option}'`);
 	                    }
 	                    return buildOption(option, value);
@@ -1092,7 +1153,7 @@
 	        }
 	    }
 	    request(params, overrides) {
-	        var _a;
+	        var _a, _b;
 	        if (overrides !== undefined) {
 	            throw new Error('request(params, overrides)` is unsupported, please use `request({ ...params, ...overrides })` instead.');
 	        }
@@ -1102,12 +1163,15 @@
 	        let { method, apiPrefix } = params;
 	        const { body, passthrough = {}, retry } = params;
 	        apiPrefix = apiPrefix !== null && apiPrefix !== void 0 ? apiPrefix : this.apiPrefix;
-	        const url = apiPrefix + this.compile(params);
+	        const url = apiPrefix + ((_a = params.url) !== null && _a !== void 0 ? _a : this.compile(params));
 	        method = method !== null && method !== void 0 ? method : 'GET';
 	        method = method.toUpperCase();
-	        const opts = Object.assign(Object.assign(Object.assign(Object.assign({}, this.passthrough), ((_a = this.passthroughByMethod[method]) !== null && _a !== void 0 ? _a : {})), passthrough), { url,
+	        // Filter to prevent accidental parameter passthrough.
+	        const opts = Object.assign(Object.assign(Object.assign(Object.assign({}, this.passthrough), ((_b = this.passthroughByMethod[method]) !== null && _b !== void 0 ? _b : {})), passthrough), { url,
 	            body,
 	            method });
+	        // Do not await this._request result, so that we can preserve
+	        // the potentially enhanced promise-like result.
 	        return this.callWithRetry(() => this._request(opts), retry);
 	    }
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pinejs-client-fetch",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "This module provides the nodejs interface for the pinejs API using request.",
   "main": "build/index.js",
   "browser": "build/index.umd.js",
@@ -49,7 +49,7 @@
     "chai-as-promised": "^7.1.2",
     "fetch-ponyfill": "^7.1.0",
     "husky": "^9.0.11",
-    "karma": "^5.2.3",
+    "karma": "^6.0.0",
     "lint-staged": "^15.2.5",
     "mocha": "^10.4.0",
     "rollup": "^2.79.1",
@@ -60,6 +60,6 @@
     "pinejs-client-core": "^6.14.7"
   },
   "versionist": {
-    "publishedAt": "2024-06-06T15:44:29.125Z"
+    "publishedAt": "2025-03-19T16:05:12.830Z"
   }
 }