ng-qubee 2.0.3 → 2.0.5

package/README.md

@@ -17,6 +17,14 @@ NgQubee uses some open source projects to work properly:
 
 And of course NgQubee itself is open source with a [public repository][ng-qubee] on GitHub.
 
+## Requirements
+
+NgQubee requires:
+- **Angular**: >=16.0.0 <22.0.0 (supports Angular 16 through 21)
+- **RxJS**: ^6.5.0 || ^7.0.0
+
+> **Note**: Angular 16+ is required because NgQubee uses Angular Signals for state management.
+
 ## Installation
 Install NgQubee via NPM
 

package/fesm2022/ng-qubee.mjs

@@ -10,6 +10,17 @@ class KeyNotFoundError extends Error {
 }
 
 class PaginatedCollection {
+    data;
+    page;
+    from;
+    to;
+    total;
+    perPage;
+    prevPageUrl;
+    nextPageUrl;
+    lastPage;
+    firstPageUrl;
+    lastPageUrl;
     constructor(data, page, from, to, total, perPage, prevPageUrl, nextPageUrl, lastPage, firstPageUrl, lastPageUrl) {
         this.data = data;
         this.page = page;
@@ -68,6 +79,13 @@ class UnselectableModelError extends Error {
 }
 
 class QueryBuilderOptions {
+    appends;
+    fields;
+    filters;
+    includes;
+    limit;
+    page;
+    sort;
     constructor(options) {
         this.appends = options.appends || 'append';
         this.fields = options.fields || 'fields';
@@ -79,6 +97,27 @@ class QueryBuilderOptions {
     }
 }
 
+class InvalidModelNameError extends Error {
+    constructor(model) {
+        super(`Invalid model name: Model name must be a non-empty string. Received: ${JSON.stringify(model)}`);
+        this.name = 'InvalidModelNameError';
+    }
+}
+
+class InvalidPageNumberError extends Error {
+    constructor(page) {
+        super(`Invalid page number: Page must be a positive integer greater than 0. Received: ${page}`);
+        this.name = 'InvalidPageNumberError';
+    }
+}
+
+class InvalidLimitError extends Error {
+    constructor(limit) {
+        super(`Invalid limit value: Limit must be a positive integer greater than 0. Received: ${limit}`);
+        this.name = 'InvalidLimitError';
+    }
+}
+
 const INITIAL_STATE = {
     baseUrl: '',
     fields: {},
@@ -90,40 +129,77 @@ const INITIAL_STATE = {
     sorts: []
 };
 class NestService {
+    /**
+     * Private writable signal that holds the Query Builder state
+     *
+     * @type {IQueryBuilderState}
+     */
+    _nest = signal(this._clone(INITIAL_STATE));
+    /**
+     * A computed signal that makes readonly the writable signal _nest
+     *
+     * @type {Signal<IQueryBuilderState>}
+     */
+    nest = computed(() => this._clone(this._nest()));
     constructor() {
-        /**
-         * Private writable signal that holds the Query Builder state
-         *
-         * @type {IQueryBuilderState}
-         */
-        this._nest = signal(this._clone(INITIAL_STATE));
-        /**
-         * A computed signal that makes readonly the writable signal _nest
-         *
-         * @type {Signal<IQueryBuilderState>}
-         */
-        this.nest = computed(() => this._clone(this._nest()));
         // Nothing to see here 👮🏻‍♀️
     }
+    /**
+     * Set the base URL for the API
+     *
+     * @param {string} baseUrl - The base URL to prepend to generated URIs
+     * @example
+     * service.baseUrl = 'https://api.example.com';
+     */
     set baseUrl(baseUrl) {
         this._nest.update(nest => ({
             ...nest,
             baseUrl
         }));
     }
+    /**
+     * Set the limit for paginated results
+     * Must be a positive integer greater than 0
+     *
+     * @param {number} limit - The number of items per page
+     * @throws {InvalidLimitError} If limit is not a positive integer
+     * @example
+     * service.limit = 25;
+     */
     set limit(limit) {
+        this._validateLimit(limit);
         this._nest.update(nest => ({
             ...nest,
             limit
         }));
     }
+    /**
+     * Set the model name for the query
+     * Must be a non-empty string
+     *
+     * @param {string} model - The model/resource name (e.g., 'users', 'posts')
+     * @throws {InvalidModelNameError} If model is not a non-empty string
+     * @example
+     * service.model = 'users';
+     */
     set model(model) {
+        this._validateModelName(model);
         this._nest.update(nest => ({
             ...nest,
             model
         }));
     }
+    /**
+     * Set the page number for pagination
+     * Must be a positive integer greater than 0
+     *
+     * @param {number} page - The page number to fetch
+     * @throws {InvalidPageNumberError} If page is not a positive integer
+     * @example
+     * service.page = 2;
+     */
     set page(page) {
+        this._validatePageNumber(page);
         this._nest.update(nest => ({
             ...nest,
             page
@@ -132,49 +208,123 @@ class NestService {
     _clone(obj) {
         return JSON.parse(JSON.stringify(obj));
     }
+    /**
+     * Validates that the model name is a non-empty string
+     *
+     * @param {string} model - The model name to validate
+     * @throws {InvalidModelNameError} If model is not a non-empty string
+     * @private
+     */
+    _validateModelName(model) {
+        if (!model || typeof model !== 'string' || model.trim().length === 0) {
+            throw new InvalidModelNameError(model);
+        }
+    }
+    /**
+     * Validates that the page number is a positive integer
+     *
+     * @param {number} page - The page number to validate
+     * @throws {InvalidPageNumberError} If page is not a positive integer
+     * @private
+     */
+    _validatePageNumber(page) {
+        if (!Number.isInteger(page) || page < 1) {
+            throw new InvalidPageNumberError(page);
+        }
+    }
+    /**
+     * Validates that the limit is a positive integer
+     *
+     * @param {number} limit - The limit value to validate
+     * @throws {InvalidLimitError} If limit is not a positive integer
+     * @private
+     */
+    _validateLimit(limit) {
+        if (!Number.isInteger(limit) || limit < 1) {
+            throw new InvalidLimitError(limit);
+        }
+    }
     /**
      * Add selectable fields for the given model to the request
+     * Automatically prevents duplicate fields for each model
      *
-     * @param {IFields} fields
+     * @param {IFields} fields - Object mapping model names to arrays of field names
      * @return {void}
-     * @todo Avoid duplicated fields
+     * @example
+     * service.addFields({ users: ['id', 'email', 'username'] });
+     * service.addFields({ posts: ['title', 'content'] });
      */
     addFields(fields) {
-        this._nest.update(nest => ({
-            ...nest,
-            fields: { ...nest.fields, ...fields }
-        }));
+        this._nest.update(nest => {
+            const mergedFields = { ...nest.fields };
+            Object.keys(fields).forEach(model => {
+                const existingFields = mergedFields[model] || [];
+                const newFields = fields[model];
+                // Use Set to prevent duplicates
+                const uniqueFields = Array.from(new Set([...existingFields, ...newFields]));
+                mergedFields[model] = uniqueFields;
+            });
+            return {
+                ...nest,
+                fields: mergedFields
+            };
+        });
     }
     /**
      * Add filters to the request
+     * Automatically prevents duplicate filter values for each filter key
      *
-     * @param {IFilters} filters
-     * @todo Avoid duplicated filters
+     * @param {IFilters} filters - Object mapping filter keys to arrays of values
+     * @return {void}
+     * @example
+     * service.addFilters({ id: [1, 2, 3] });
+     * service.addFilters({ status: ['active', 'pending'] });
      */
     addFilters(filters) {
-        this._nest.update(nest => ({
-            ...nest,
-            filters: { ...nest.filters, ...filters }
-        }));
+        this._nest.update(nest => {
+            const mergedFilters = { ...nest.filters };
+            Object.keys(filters).forEach(key => {
+                const existingValues = mergedFilters[key] || [];
+                const newValues = filters[key];
+                // Use Set to prevent duplicates
+                const uniqueValues = Array.from(new Set([...existingValues, ...newValues]));
+                mergedFilters[key] = uniqueValues;
+            });
+            return {
+                ...nest,
+                filters: mergedFilters
+            };
+        });
     }
     /**
      * Add resources to include with the request
+     * Automatically prevents duplicate includes
      *
-     * @param {string[]} includes  models to include to the request
+     * @param {string[]} includes - Array of model names to include in the response
      * @return {void}
-     * @todo Avoid duplicated includes
+     * @example
+     * service.addIncludes(['profile', 'posts']);
+     * service.addIncludes(['comments']);
      */
     addIncludes(includes) {
-        this._nest.update(nest => ({
-            ...nest,
-            includes: [...nest.includes, ...includes]
-        }));
+        this._nest.update(nest => {
+            // Use Set to prevent duplicates
+            const uniqueIncludes = Array.from(new Set([...nest.includes, ...includes]));
+            return {
+                ...nest,
+                includes: uniqueIncludes
+            };
+        });
     }
     /**
      * Add a field that should be used for sorting data
      *
-     * @param {ISort} sort
+     * @param {ISort} sort - Sort configuration with field name and order (ASC/DESC)
      * @return {void}
+     * @example
+     * import { SortEnum } from 'ng-qubee';
+     * service.addSort({ field: 'created_at', order: SortEnum.DESC });
+     * service.addSort({ field: 'name', order: SortEnum.ASC });
      */
     addSort(sort) {
         this._nest.update(nest => ({
@@ -184,16 +334,22 @@ class NestService {
     }
     /**
      * Remove fields for the given model
+     * Uses deep cloning to prevent mutations to the original state
      *
-     * @param {IFields} fields
+     * @param {IFields} fields - Object mapping model names to arrays of field names to remove
+     * @return {void}
+     * @example
+     * service.deleteFields({ users: ['email'] });
+     * service.deleteFields({ posts: ['content', 'body'] });
      */
     deleteFields(fields) {
-        const f = Object.assign({}, this.nest().fields);
+        // Deep clone the fields object to prevent mutations
+        const f = this._clone(this._nest().fields);
         Object.keys(fields).forEach(k => {
             if (!(k in f)) {
                 return;
             }
-            f[k] = this._nest().fields[k].filter(v => !fields[k].includes(v));
+            f[k] = f[k].filter(v => !fields[k].includes(v));
         });
         this._nest.update(nest => ({
             ...nest,
@@ -201,12 +357,18 @@ class NestService {
         }));
     }
     /**
+     * Remove filters from the request
+     * Uses deep cloning to prevent mutations to the original state
      *
-     * @param filters
-     * @todo Create a clone of the filter obj before assigning to f
+     * @param {...string[]} filters - Filter keys to remove
+     * @return {void}
+     * @example
+     * service.deleteFilters('id');
+     * service.deleteFilters('status', 'type');
      */
     deleteFilters(...filters) {
-        const f = Object.assign({}, this._nest().filters);
+        // Deep clone the filters object to prevent mutations
+        const f = this._clone(this._nest().filters);
         filters.forEach(k => delete f[k]);
         this._nest.update(nest => ({
             ...nest,
@@ -214,8 +376,13 @@ class NestService {
         }));
     }
     /**
+     * Remove includes from the request
      *
-     * @param includes
+     * @param {...string[]} includes - Include names to remove
+     * @return {void}
+     * @example
+     * service.deleteIncludes('profile');
+     * service.deleteIncludes('posts', 'comments');
      */
     deleteIncludes(...includes) {
         this._nest.update(nest => ({
@@ -224,8 +391,13 @@ class NestService {
         }));
     }
     /**
+     * Remove sorts from the request by field name
      *
-     * @param sorts
+     * @param {...string[]} sorts - Field names of sorts to remove
+     * @return {void}
+     * @example
+     * service.deleteSorts('created_at');
+     * service.deleteSorts('name', 'created_at');
      */
     deleteSorts(...sorts) {
         const s = [...this._nest().sorts];
@@ -240,25 +412,36 @@ class NestService {
             sorts: s
         }));
     }
+    /**
+     * Reset the query builder state to initial values
+     * Clears all fields, filters, includes, sorts, and resets pagination
+     *
+     * @return {void}
+     * @example
+     * service.reset();
+     * // State is now: { baseUrl: '', fields: {}, filters: {}, includes: [], limit: 15, model: '', page: 1, sorts: [] }
+     */
     reset() {
         this._nest.update(_ => this._clone(INITIAL_STATE));
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: NestService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: NestService }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: NestService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: NestService });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: NestService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: NestService, decorators: [{
             type: Injectable
         }], ctorParameters: () => [] });
 
 class NgQubeeService {
+    _nestService;
+    _options;
+    /**
+     * This property serves as an accumulator for holding the composed string with each query param
+     */
+    _uri = '';
+    _uri$ = new BehaviorSubject('');
+    uri$ = this._uri$.asObservable().pipe(filter(uri => !!uri));
     constructor(_nestService, options = {}) {
         this._nestService = _nestService;
-        /**
-         * This property serves as an accumulator for holding the composed string with each query param
-         */
-        this._uri = '';
-        this._uri$ = new BehaviorSubject('');
-        this.uri$ = this._uri$.asObservable().pipe(filter(uri => !!uri));
         this._options = new QueryBuilderOptions(options);
     }
     _parseFields(s) {
@@ -350,12 +533,6 @@ class NgQubeeService {
     _prepend(model) {
         return this._uri ? '&' : `/${model}?`;
     }
-    // private _removeArgIfEmpty(arg: string): string {
-    //   const params = new URL(this._uri).searchParams;
-    //   if (!params.get(arg)) {
-    //     params.delete(arg);
-    //   }
-    // }
     /**
      * Add fields to the select statement for the given model
      *
@@ -546,10 +723,10 @@ class NgQubeeService {
         this._nestService.page = page;
         return this;
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: NgQubeeService, deps: [{ token: NestService }, { token: 'QUERY_PARAMS_CONFIG', optional: true }], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: NgQubeeService }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: NgQubeeService, deps: [{ token: NestService }, { token: 'QUERY_PARAMS_CONFIG', optional: true }], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: NgQubeeService });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: NgQubeeService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: NgQubeeService, decorators: [{
             type: Injectable
         }], ctorParameters: () => [{ type: NestService }, { type: undefined, decorators: [{
                     type: Inject,
@@ -559,6 +736,18 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.1.3", ngImpor
                 }] }] });
 
 class ResponseOptions {
+    currentPage;
+    data;
+    firstPageUrl;
+    from;
+    lastPage;
+    lastPageUrl;
+    nextPageUrl;
+    path;
+    perPage;
+    prevPageUrl;
+    to;
+    total;
     constructor(options) {
         this.currentPage = options.currentPage || 'current_page';
         this.data = options.data || 'data';
@@ -576,16 +765,18 @@ class ResponseOptions {
 }
 
 class PaginationService {
+    _options;
     constructor(options = {}) {
         this._options = new ResponseOptions(options);
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     paginate(response) {
         return new PaginatedCollection(response[this._options.data], response[this._options.currentPage], response[this._options.from], response[this._options.to], response[this._options.total], response[this._options.perPage], response[this._options.prevPageUrl], response[this._options.nextPageUrl], response[this._options.lastPage], response[this._options.firstPageUrl], response[this._options.lastPageUrl]);
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: PaginationService, deps: [{ token: 'RESPONSE_OPTIONS', optional: true }], target: i0.ɵɵFactoryTarget.Injectable }); }
-    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: PaginationService }); }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: PaginationService, deps: [{ token: 'RESPONSE_OPTIONS', optional: true }], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: PaginationService });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: PaginationService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: PaginationService, decorators: [{
             type: Injectable
         }], ctorParameters: () => [{ type: undefined, decorators: [{
                     type: Inject,
@@ -612,15 +803,15 @@ class NgQubeeModule {
             ]
         };
     }
-    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: NgQubeeModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule }); }
-    static { this.ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "17.1.3", ngImport: i0, type: NgQubeeModule }); }
-    static { this.ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: NgQubeeModule, providers: [{
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: NgQubeeModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
+    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "19.0.5", ngImport: i0, type: NgQubeeModule });
+    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: NgQubeeModule, providers: [{
                 deps: [NestService],
                 provide: NgQubeeService,
                 useFactory: (nestService) => new NgQubeeService(nestService, {})
-            }] }); }
+            }] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.1.3", ngImport: i0, type: NgQubeeModule, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.0.5", ngImport: i0, type: NgQubeeModule, decorators: [{
             type: NgModule,
             args: [{
                     providers: [{
@@ -674,5 +865,5 @@ function provideNgQubee(config = {}) {
  * Generated bundle index. Do not edit.
  */
 
-export { NgQubeeModule, NgQubeeService, PaginatedCollection, PaginationService, provideNgQubee };
+export { InvalidLimitError, InvalidModelNameError, InvalidPageNumberError, KeyNotFoundError, NgQubeeModule, NgQubeeService, PaginatedCollection, PaginationService, UnselectableModelError, provideNgQubee };
 //# sourceMappingURL=ng-qubee.mjs.map