@ecodev/natural 62.1.2 → 62.3.0

package/vanilla/src/lib/services/abstract-model.service.d.ts

@@ -0,0 +1,244 @@
+import { Apollo, MutationResult } from 'apollo-angular';
+import { FetchResult, WatchQueryFetchPolicy } from '@apollo/client/core';
+import { AbstractControl, AsyncValidatorFn, UntypedFormGroup, ValidatorFn } from '@angular/forms';
+import { DocumentNode } from 'graphql';
+import { Observable, OperatorFunction } from 'rxjs';
+import { NaturalQueryVariablesManager, QueryVariables } from '../classes/query-variable-manager';
+import { Literal } from '../types/types';
+import { PaginatedData } from '../classes/data-source';
+import { NaturalDebounceService } from './debounce.service';
+export type FormValidators = Record<string, ValidatorFn[]>;
+export type FormAsyncValidators = Record<string, AsyncValidatorFn[]>;
+export type VariablesWithInput = {
+    input: Literal;
+};
+export type FormControls = Record<string, AbstractControl>;
+export type WithId<T> = {
+    id: string;
+} & T;
+export declare abstract class NaturalAbstractModelService<Tone, Vone extends {
+    id: string;
+}, Tall extends PaginatedData<Literal>, Vall extends QueryVariables, Tcreate, Vcreate extends VariablesWithInput, Tupdate, Vupdate extends {
+    id: string;
+    input: Literal;
+}, Tdelete, Vdelete extends {
+    ids: string[];
+}> {
+    protected readonly name: string;
+    protected readonly oneQuery: DocumentNode | null;
+    protected readonly allQuery: DocumentNode | null;
+    protected readonly createMutation: DocumentNode | null;
+    protected readonly updateMutation: DocumentNode | null;
+    protected readonly deleteMutation: DocumentNode | null;
+    private readonly createName;
+    private readonly updateName;
+    private readonly deleteName;
+    /**
+     * Store the creation mutations that are pending
+     */
+    private readonly creatingCache;
+    protected readonly apollo: Apollo;
+    protected readonly naturalDebounceService: NaturalDebounceService;
+    private readonly plural;
+    /**
+     *
+     * @param name service and single object query name (eg. userForFront or user).
+     * @param oneQuery GraphQL query to fetch a single object from ID (eg. userForCrudQuery).
+     * @param allQuery GraphQL query to fetch a filtered list of objects (eg. usersForCrudQuery).
+     * @param createMutation GraphQL mutation to create an object.
+     * @param updateMutation GraphQL mutation to update an object.
+     * @param deleteMutation GraphQL mutation to delete a list of objects.
+     * @param plural list query name (eg. usersForFront or users).
+     * @param createName create object mutation name (eg. createUser).
+     * @param updateName update object mutation name (eg. updateUser).
+     * @param deleteName delete object mutation name (eg. deleteUsers).
+     */
+    constructor(name: string, oneQuery: DocumentNode | null, allQuery: DocumentNode | null, createMutation: DocumentNode | null, updateMutation: DocumentNode | null, deleteMutation: DocumentNode | null, plural?: string | null, createName?: string | null, updateName?: string | null, deleteName?: string | null);
+    /**
+     * List of individual fields validators
+     */
+    getFormValidators(model?: Literal): FormValidators;
+    /**
+     * List of individual async fields validators
+     */
+    getFormAsyncValidators(model?: Literal): FormAsyncValidators;
+    /**
+     * List of grouped fields validators (like password + confirm password)
+     */
+    getFormGroupValidators(model?: Literal): ValidatorFn[];
+    /**
+     * List of async group fields validators (like unique constraint on multiple columns)
+     */
+    getFormGroupAsyncValidators(model?: Literal): AsyncValidatorFn[];
+    getFormConfig(model: Literal): FormControls;
+    /**
+     * Create the final FormGroup for the object, including all validators
+     *
+     * This method should **not** be overridden, but instead `getFormConfig`,
+     * `getFormGroupValidators`, `getFormGroupAsyncValidators` might be.
+     */
+    getFormGroup(model: Literal): UntypedFormGroup;
+    /**
+     * Get a single object
+     *
+     * If available it will emit object from cache immediately, then it
+     * will **always** fetch from network and then the observable will be completed.
+     *
+     * You must subscribe to start getting results (and fetch from network).
+     */
+    getOne(id: string): Observable<Tone>;
+    /**
+     * Watch a single object
+     *
+     * If available it will emit object from cache immediately, then it
+     * will **always** fetch from network, and then keep watching the cache forever.
+     *
+     * You must subscribe to start getting results (and fetch from network).
+     *
+     * You **MUST** unsubscribe.
+     */
+    watchOne(id: string, fetchPolicy?: WatchQueryFetchPolicy): Observable<Tone>;
+    private prepareOneQuery;
+    /**
+     * Get a collection of objects
+     *
+     * It will **always** fetch from network and then the observable will be completed.
+     * No cache is ever used, so it's slow but correct.
+     */
+    getAll(queryVariablesManager: NaturalQueryVariablesManager<Vall>): Observable<Tall>;
+    /**
+     * Get a collection of objects
+     *
+     * Every time the observable variables change, and they are not undefined,
+     * it will return result from cache, then it will **always** fetch from network,
+     * and then keep watching the cache forever.
+     *
+     * You must subscribe to start getting results (and fetch from network).
+     *
+     * You **MUST** unsubscribe.
+     */
+    watchAll(queryVariablesManager: NaturalQueryVariablesManager<Vall>, fetchPolicy?: WatchQueryFetchPolicy): Observable<Tall>;
+    /**
+     * This functions allow to quickly create or update objects.
+     *
+     * Manages a "creation is pending" status, and update when creation is ready.
+     * Uses regular update/updateNow and create methods.
+     * Used mainly when editing multiple objects in same controller (like in editable arrays)
+     */
+    createOrUpdate(object: Vcreate['input'] | WithId<Vupdate['input']>, now?: boolean): Observable<Tcreate | Tupdate>;
+    /**
+     * Create an object in DB and then refetch the list of objects
+     */
+    create(object: Vcreate['input']): Observable<Tcreate>;
+    /**
+     * Update an object, after a short debounce
+     */
+    update(object: WithId<Vupdate['input']>): Observable<Tupdate>;
+    /**
+     * Update an object immediately when subscribing
+     */
+    updateNow(object: WithId<Vupdate['input']>): Observable<Tupdate>;
+    /**
+     * Delete objects and then refetch the list of objects
+     */
+    delete(objects: {
+        id: string;
+    }[]): Observable<Tdelete>;
+    /**
+     * If the id is provided, resolves an observable model. The observable model will only be emitted after we are sure
+     * that Apollo cache is fresh and warm. Then the component can subscribe to the observable model to get the model
+     * immediately from Apollo cache and any subsequents future mutations that may happen to Apollo cache.
+     *
+     * Without id, returns default values, in order to show a creation form.
+     */
+    resolve(id: string | undefined): Observable<Observable<Tone | Vcreate['input']>>;
+    /**
+     * Return an object that match the GraphQL input type.
+     * It creates an object with manually filled data and add uncompleted data (like required attributes that can be empty strings)
+     */
+    getInput(object: Literal, forCreation: boolean): Vcreate['input'] | Vupdate['input'];
+    /**
+     * Return the number of objects matching the query. It may never complete.
+     *
+     * This is used for the unique validator
+     */
+    count(queryVariablesManager: NaturalQueryVariablesManager<Vall>): Observable<number>;
+    /**
+     * Return empty object with some default values from server perspective
+     *
+     * This is typically useful when showing a form for creation
+     */
+    getDefaultForServer(): Vcreate['input'];
+    /**
+     * You probably **should not** use this.
+     *
+     * If you are trying to *call* this method, instead you probably want to call `getDefaultForServer()` to get default
+     * values for a model, or `getFormConfig()` to get a configured form that includes extra form fields.
+     *
+     * If you are trying to *override* this method, instead you probably want to override `getDefaultForServer()`.
+     *
+     * The only and **very rare** reason to override this method is if the client needs extra form fields that cannot be
+     * accepted by the server (not part of `XXXInput` type) and that are strictly for the client form needs. In that case,
+     * then you can return default values for those extra form fields, and the form returned by `getFormConfig()` will
+     * include those extra fields.
+     */
+    protected getFormExtraFieldDefaultValues(): Literal;
+    /**
+     * This is used to extract only the array of fetched objects out of the entire fetched data
+     */
+    protected mapAll(): OperatorFunction<FetchResult<unknown>, Tall>;
+    /**
+     * This is used to extract only the created object out of the entire fetched data
+     */
+    protected mapCreation(result: MutationResult<unknown>): Tcreate;
+    /**
+     * This is used to extract only the updated object out of the entire fetched data
+     */
+    protected mapUpdate(result: MutationResult<unknown>): Tupdate;
+    /**
+     * This is used to extract only flag when deleting an object
+     */
+    protected mapDelete(result: MutationResult<unknown>): Tdelete;
+    /**
+     * Returns additional variables to be used when getting a single object
+     *
+     * This is typically a site or state ID, and is needed to get appropriate access rights
+     */
+    protected getPartialVariablesForOne(): Observable<Partial<Vone>>;
+    /**
+     * Returns additional variables to be used when getting multiple objects
+     *
+     * This is typically a site or state ID, but it could be something else to further filter the query
+     */
+    getPartialVariablesForAll(): Observable<Partial<Vall>>;
+    /**
+     * Returns additional variables to be used when creating an object
+     *
+     * This is typically a site or state ID
+     */
+    protected getPartialVariablesForCreation(object: Literal): Partial<Vcreate>;
+    /**
+     * Returns additional variables to be used when updating an object
+     *
+     * This is typically a site or state ID
+     */
+    protected getPartialVariablesForUpdate(object: Literal): Partial<Vupdate>;
+    /**
+     * Return additional variables to be used when deleting an object
+     *
+     * This is typically a site or state ID
+     */
+    protected getPartialVariablesForDelete(objects: Literal[]): Partial<Vdelete>;
+    /**
+     * Throw exception to prevent executing queries with invalid variables
+     */
+    protected throwIfObservable(value: unknown): void;
+    /**
+     * Merge given ID with additional partial variables if there is any
+     */
+    private getVariablesForOne;
+    /**
+     * Throw exception to prevent executing null queries
+     */
+    private throwIfNotQuery;
+}

package/vanilla/src/lib/services/debounce.service.d.ts

@@ -0,0 +1,52 @@
+import { Observable } from 'rxjs';
+import { UntypedModelService } from '../types/types';
+import * as i0 from "@angular/core";
+/**
+ * Debounce subscriptions to update mutations, with the possibility to cancel one, flush one, or flush all of them.
+ *
+ * `modelService` is also used to separate objects by their types. So User with ID 1 is not confused with Product with ID 1.
+ *
+ * `id` must be the ID of the object that will be updated.
+ */
+export declare class NaturalDebounceService {
+    /**
+     * Stores the debounced update function
+     */
+    private readonly allDebouncedUpdateCache;
+    /**
+     * Debounce the `modelService.updateNow()` mutation for a short time. If called multiple times with the same
+     * modelService and id, it will postpone the subscription to the mutation.
+     *
+     * All input variables for the same object (same service and ID) will be cumulated over time. So it is possible
+     * to update `field1`, then `field2`, and they will be batched into a single XHR including `field1` and `field2`.
+     *
+     * But it will always keep the same debouncing timeline.
+     */
+    debounce<T extends UntypedModelService>(modelService: UntypedModelService, id: string, object: Parameters<T['updateNow']>[0]): ReturnType<T['updateNow']>;
+    cancelOne(modelService: UntypedModelService, id: string): void;
+    /**
+     * Immediately execute the pending update, if any.
+     *
+     * It should typically be called before resolving the object, to mutate it before re-fetching it from server.
+     *
+     * The returned observable will complete when the update completes, even if it errors.
+     */
+    flushOne(modelService: UntypedModelService, id: string): Observable<void>;
+    /**
+     * Immediately execute all pending updates.
+     *
+     * It should typically be called before login out.
+     *
+     * The returned observable will complete when all updates complete, even if some of them error.
+     */
+    flush(): Observable<void>;
+    private internalFlush;
+    /**
+     * Count of pending updates
+     */
+    get count(): number;
+    private getMap;
+    private delete;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NaturalDebounceService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NaturalDebounceService>;
+}

package/vanilla/src/lib/types/types.d.ts

@@ -0,0 +1,100 @@
+import { PaginatedData } from '../classes/data-source';
+import { NaturalAbstractModelService, VariablesWithInput } from '../services/abstract-model.service';
+import { QueryVariables } from '../classes/query-variable-manager';
+import { ObservedValueOf } from 'rxjs';
+import { ResolveData } from '@angular/router';
+/**
+ * An object literal with any keys and values
+ */
+export type Literal = Record<string, any>;
+/**
+ * An object with either a name or a fullName (or maybe both)
+ */
+export type NameOrFullName = {
+    id: string;
+    name: string;
+    fullName?: string;
+} | {
+    id: string;
+    name?: string;
+    fullName: string;
+};
+/**
+ * Extract the Tone type from a NaturalAbstractModelService
+ */
+export type ExtractTone<P> = P extends NaturalAbstractModelService<infer Tone, any, any, any, any, any, any, any, any, any> ? Tone : never;
+/**
+ * Extract the Vone type from a NaturalAbstractModelService
+ */
+export type ExtractVone<P> = P extends NaturalAbstractModelService<any, infer Vone, any, any, any, any, any, any, any, any> ? Vone extends {
+    id: string;
+} ? Vone : never : never;
+/**
+ * Extract the Tall type from a NaturalAbstractModelService
+ */
+export type ExtractTall<P> = P extends NaturalAbstractModelService<any, any, infer Tall, any, any, any, any, any, any, any> ? Tall extends PaginatedData<Literal> ? Tall : never : never;
+/**
+ * Extract the TallOne type for a single item coming from a list of items from a NaturalAbstractModelService
+ */
+export type ExtractTallOne<P> = P extends NaturalAbstractModelService<any, any, PaginatedData<infer TallOne extends Literal>, any, any, any, any, any, any, any> ? TallOne extends Literal ? TallOne : never : never;
+/**
+ * Extract the Vall type from a NaturalAbstractModelService
+ */
+export type ExtractVall<P> = P extends NaturalAbstractModelService<any, any, any, infer Vall, any, any, any, any, any, any> ? Vall extends QueryVariables ? Vall : never : never;
+/**
+ * Extract the Tcreate type from a NaturalAbstractModelService
+ */
+export type ExtractTcreate<P> = P extends NaturalAbstractModelService<any, any, any, any, infer Tcreate, any, any, any, any, any> ? Tcreate : never;
+/**
+ * Extract the Vcreate type from a NaturalAbstractModelService
+ */
+export type ExtractVcreate<P> = P extends NaturalAbstractModelService<any, any, any, any, any, infer Vcreate, any, any, any, any> ? Vcreate extends VariablesWithInput ? Vcreate : never : never;
+/**
+ * Extract the Tupdate type from a NaturalAbstractModelService
+ */
+export type ExtractTupdate<P> = P extends NaturalAbstractModelService<any, any, any, any, any, any, infer Tupdate, any, any, any> ? Tupdate : never;
+/**
+ * Extract the Vupdate type from a NaturalAbstractModelService
+ */
+export type ExtractVupdate<P> = P extends NaturalAbstractModelService<any, any, any, any, any, any, any, infer Vupdate, any, any> ? Vupdate extends {
+    id: string;
+    input: Literal;
+} ? Vupdate : never : never;
+/**
+ * Extract the Tdelete type from a NaturalAbstractModelService
+ */
+export type ExtractTdelete<P> = P extends NaturalAbstractModelService<any, any, any, any, any, any, any, any, infer Tdelete, any> ? Tdelete : never;
+/**
+ * Extract the Vdelete type from a NaturalAbstractModelService
+ */
+export type ExtractVdelete<P> = P extends NaturalAbstractModelService<any, any, any, any, any, any, any, any, any, infer Vdelete> ? Vdelete extends {
+    ids: string[];
+} ? Vdelete : never : never;
+/**
+ * Extract the resolve type from a NaturalAbstractModelService
+ */
+export type ExtractResolve<P> = P extends NaturalAbstractModelService<any, any, any, any, any, any, any, any, any, any> ? ObservedValueOf<ObservedValueOf<ReturnType<P['resolve']>>> : never;
+/**
+ * This should be avoided if possible, and instead use a more precise type with some constraints on it to ensure that the model
+ * service is able to fulfill its requirements.
+ */
+export type UntypedModelService = NaturalAbstractModelService<any, any, any, any, any, any, any, any, any, any>;
+/**
+ * Returns the resolved data type, as available in components, from the given resolvers
+ *
+ * Eg:
+ *
+ * ```ts
+ * const actionResolvers = {
+ *     model: resolveAction,
+ *     statuses: () => inject(NaturalEnumService).get('Status'),
+ * } as const;
+ *
+ * // In action.component.ts
+ * const data: ResolvedData<typeof actionResolvers>;
+ * data.statuses.forEach(...);
+ * ```
+ */
+export type ResolvedData<T extends ResolveData> = {
+    readonly [KeyType in keyof Pick<T, keyof T>]: ObservedValueOf<ReturnType<Pick<T, keyof T>[KeyType]>>;
+};

package/esm2022/ecodev-natural.mjs

@@ -1,5 +0,0 @@
-/**
- * Generated bundle index. Do not edit.
- */
-export * from './public-api';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZWNvZGV2LW5hdHVyYWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9wcm9qZWN0cy9uYXR1cmFsL3NyYy9lY29kZXYtbmF0dXJhbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQTs7R0FFRztBQUVILGNBQWMsY0FBYyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqXG4gKiBHZW5lcmF0ZWQgYnVuZGxlIGluZGV4LiBEbyBub3QgZWRpdC5cbiAqL1xuXG5leHBvcnQgKiBmcm9tICcuL3B1YmxpYy1hcGknO1xuIl19