@ecodev/natural 62.1.2 → 63.0.0

package/vanilla/src/lib/classes/query-variable-manager.d.ts

@@ -0,0 +1,91 @@
+import { BehaviorSubject } from 'rxjs';
+export type QueryVariables = {
+    filter?: any | null;
+    pagination?: PaginationInput | null;
+    sorting?: Sorting[] | null;
+};
+export type PaginationInput = {
+    offset?: number | null;
+    pageIndex?: number | null;
+    pageSize?: number | null;
+};
+export type Sorting = {
+    field: any;
+    order?: SortingOrder | null;
+    nullAsHighest?: boolean | null;
+    emptyStringAsHighest?: boolean | null;
+};
+export declare enum SortingOrder {
+    ASC = "ASC",
+    DESC = "DESC"
+}
+/**
+ * Filter manager stores a set of channels that contain a variable object and exposes an observable "variables" that updates with the result
+ * of all channels merged together.
+ *
+ * A channel is supposed to be used by a given aspect of the GUI (pagination, sorting, search, others ?).
+ *
+ * ```ts
+ * const fm = new QueryVariablesManager();
+ * fm.merge('componentA-variables', {a : [1, 2, 3]});
+ * ```
+ *
+ * Variables attributes is a BehaviorSubject. That mean it's not mandatory to subscribe, we can just call getValue or value attributes on
+ * it :
+ *
+ * ```ts
+ * console.log(fm.variables.value); // {a : [1, 2, 3]}
+ * ```
+ *
+ * Set new variables for 'componentA-variables':
+ *
+ * ```ts
+ * fm.merge('componentA-variables', {a : [1, 2]});
+ * console.log(fm.variables.value); // {a : [1, 2, 3]}
+ * ```
+ *
+ * Set new variables for new channel:
+ *
+ * ```ts
+ * fm.merge('componentB-variables', {a : [3, 4]});
+ * console.log(fm.variables.value); // {a : [1, 2, 3, 4]}
+ * ```
+ */
+export declare class NaturalQueryVariablesManager<T extends QueryVariables = QueryVariables> {
+    readonly variables: BehaviorSubject<T | undefined>;
+    private readonly channels;
+    constructor(queryVariablesManager?: NaturalQueryVariablesManager<T>);
+    /**
+     * Set or override all the variables that may exist in the given channel
+     */
+    set(channelName: string, variables: Partial<T> | null | undefined): void;
+    /**
+     * Return a deep clone of the variables for the given channel name.
+     *
+     * Avoid returning the same reference to prevent an attribute change, then another channel update that would
+     * used this changed attribute without having explicitly asked QueryVariablesManager to update it.
+     */
+    get(channelName: string): Partial<T> | undefined;
+    /**
+     * Merge variable into a channel, overriding arrays in same channel / key
+     */
+    merge(channelName: string, newVariables: Partial<T>): void;
+    /**
+     * Apply default values to a channel
+     * Note : lodash defaults only defines values on destinations keys that are undefined
+     */
+    defaults(channelName: string, newVariables: Partial<T>): void;
+    private getChannelsCopy;
+    /**
+     * Merge channels in a single object
+     * Arrays are concatenated
+     * Filter groups are combined smartly (see mergeGroupList)
+     */
+    private updateVariables;
+    /**
+     * Cross merge two filters
+     * Only accepts groups with same groupLogic (ignores the first one, because there is no groupLogic in this one)
+     * @throws In case two non-empty lists of groups are given and at one of them mix groupLogic value, throws an error
+     */
+    private mergeGroupList;
+}

package/vanilla/src/lib/classes/signing.d.ts

@@ -0,0 +1,7 @@
+import { HttpInterceptorFn } from '@angular/common/http';
+/**
+ * Sign all HTTP POST requests that are GraphQL queries against `/graphql` endpoint with a custom signature.
+ *
+ * The server will validate the signature before executing the GraphQL query.
+ */
+export declare function graphqlQuerySigner(key: string): HttpInterceptorFn;

package/vanilla/src/lib/classes/utility.d.ts

@@ -0,0 +1,77 @@
+import { Literal } from '../types/types';
+import type { ReadonlyDeep } from 'type-fest';
+import { PaginationInput, Sorting } from './query-variable-manager';
+/**
+ * Very basic formatting to get only date, without time and ignoring entirely the timezone
+ *
+ * So something like: "2021-09-23"
+ */
+export declare function formatIsoDate(date: null): null;
+export declare function formatIsoDate(date: Date): string;
+export declare function formatIsoDate(date: Date | null): string | null;
+/**
+ * Format a date and time in a way that will preserve the local time zone.
+ * This allows the server side to know the day (without time) that was selected on client side.
+ *
+ * So something like: "2021-09-23T17:57:16+09:00"
+ */
+export declare function formatIsoDateTime(date: Date): string;
+/**
+ * Relations to full objects are converted to their IDs only.
+ *
+ * So {user: {id: 123}} becomes {user: 123}
+ */
+export declare function relationsToIds(object: Literal): Literal;
+/**
+ * Returns the plural form of the given name
+ *
+ * This is **not** necessarily valid english grammar. Its only purpose is for internal usage, not for humans.
+ *
+ * This **MUST** be kept in sync with `\Ecodev\Felix\Api\Plural:make()`.
+ *
+ * This is a bit performance-sensitive, so we should keep it fast and only cover cases that we actually need.
+ */
+export declare function makePlural(name: string): string;
+/**
+ * Returns the string with the first letter as capital
+ */
+export declare function upperCaseFirstLetter(term: string): string;
+/**
+ * Replace all attributes of first object with the ones provided by the second, but keeps the reference
+ */
+export declare function replaceObjectKeepingReference(obj: Literal | null, newObj: Literal | null): void;
+/**
+ * Get contrasted color for text in the slider thumb
+ * @param hexBgColor string in hexadecimals representing the background color
+ */
+export declare function getForegroundColor(hexBgColor: string): 'black' | 'white';
+/**
+ * Convert RGB color to hexadecimal color
+ *
+ * ```ts
+ * rgbToHex('rgb(255, 00, 255)'); // '#FF00FF'
+ * ```
+ */
+export declare function rgbToHex(rgb: string): string;
+/**
+ * During lodash.mergeWith, overrides arrays
+ */
+export declare function mergeOverrideArray(destValue: unknown, source: unknown): unknown;
+/**
+ * Copy text to clipboard.
+ * Accepts line breaks `\n` as textarea do.
+ */
+export declare function copyToClipboard(document: Document, text: string): void;
+export declare function deepFreeze<T extends Literal>(o: T): ReadonlyDeep<T>;
+/**
+ * Return a valid PaginationInput from whatever is available from data. Invalid properties/types will be dropped.
+ */
+export declare function validatePagination(data: unknown): PaginationInput | null;
+/**
+ * Return a valid Sortings from whatever is available from data. Invalid properties/types will be dropped.
+ */
+export declare function validateSorting(data: unknown): Sorting[] | null;
+/**
+ * Return valid columns from whatever is available from data. Invalid properties/types will be dropped.
+ */
+export declare function validateColumns(data: unknown): string[] | null;

package/vanilla/src/lib/modules/search/classes/graphql-doctrine.types.d.ts

@@ -0,0 +1,83 @@
+import { Literal } from '../../../types/types';
+export type Filter = {
+    groups?: FilterGroup[] | null;
+};
+export type FilterGroup = {
+    groupLogic?: LogicalOperator | null;
+    conditionsLogic?: LogicalOperator | null;
+    joins?: FilterGroupJoin | null;
+    conditions?: FilterGroupCondition[] | null;
+};
+export type FilterGroupJoin = Record<string, JoinOn>;
+export type JoinOn = {
+    type?: JoinType | null;
+    joins?: FilterGroupJoin | null;
+    conditions?: FilterGroupCondition[] | null;
+};
+export declare enum LogicalOperator {
+    AND = "AND",
+    OR = "OR"
+}
+export declare enum JoinType {
+    innerJoin = "innerJoin",
+    leftJoin = "leftJoin"
+}
+export type FilterGroupCondition = Record<string, FilterGroupConditionField>;
+export type FilterGroupConditionField = {
+    between?: BetweenOperator | null;
+    equal?: EqualOperator | null;
+    greater?: GreaterOperator | null;
+    greaterOrEqual?: GreaterOrEqualOperator | null;
+    in?: InOperator | null;
+    less?: LessOperator | null;
+    lessOrEqual?: LessOrEqualOperator | null;
+    like?: LikeOperator | null;
+    null?: NullOperator | null;
+    have?: HaveOperator | null;
+    empty?: EmptyOperator | null;
+    [key: string]: Literal | undefined | null;
+};
+export type Scalar = number | string | boolean;
+export type HaveOperator = {
+    values: string[];
+    not?: boolean | null;
+};
+export type EmptyOperator = {
+    not?: boolean | null;
+};
+export type BetweenOperator = {
+    from: Scalar;
+    to: Scalar;
+    not?: boolean | null;
+};
+export type EqualOperator = {
+    value: Scalar;
+    not?: boolean | null;
+};
+export type GreaterOperator = {
+    value: Scalar;
+    not?: boolean | null;
+};
+export type GreaterOrEqualOperator = {
+    value: Scalar;
+    not?: boolean | null;
+};
+export type InOperator = {
+    values: Scalar[];
+    not?: boolean | null;
+};
+export type LessOperator = {
+    value: Scalar;
+    not?: boolean | null;
+};
+export type LessOrEqualOperator = {
+    value: Scalar;
+    not?: boolean | null;
+};
+export type LikeOperator = {
+    value: Scalar;
+    not?: boolean | null;
+};
+export type NullOperator = {
+    not?: boolean | null;
+};

package/vanilla/src/lib/modules/search/classes/utils.d.ts

@@ -0,0 +1,17 @@
+import { Facet, NaturalSearchFacets } from '../types/facet';
+import { NaturalSearchSelection } from '../types/values';
+/**
+ * Lookup a facet by its `name` and then by its `field`, or return null if not found
+ */
+export declare function getFacetFromSelection(facets: NaturalSearchFacets | null, selection: NaturalSearchSelection): Facet | null;
+/**
+ * Deep clone a literal via JSON serializing/unserializing
+ *
+ * It will **not** work with:
+ *
+ *     - functions (will be removed)
+ *     - `undefined` (will be removed)
+ *     - cyclic references (will crash)
+ *     - objects (will be converted to `{}`)
+ */
+export declare function deepClone<T>(obj: T extends undefined ? never : T): T;

package/vanilla/src/lib/modules/search/types/dropdown-component.d.ts

@@ -0,0 +1,20 @@
+import { BehaviorSubject } from 'rxjs';
+import { FilterGroupConditionField } from '../classes/graphql-doctrine.types';
+export type DropdownComponent = {
+    /**
+     * Observable of current value as string
+     */
+    readonly renderedValue: BehaviorSubject<string>;
+    /**
+     * Get condition, including rich object types
+     */
+    getCondition(): FilterGroupConditionField;
+    /**
+     * Returns true if dropdown value is valid
+     */
+    isValid(): boolean;
+    /**
+     * Returns true if the dropdown value has change
+     */
+    isDirty(): boolean;
+};

package/vanilla/src/lib/modules/search/types/facet.d.ts

@@ -0,0 +1,75 @@
+import { Type } from '@angular/core';
+import { DropdownComponent } from './dropdown-component';
+import { NaturalSearchSelection } from './values';
+type BasicFacet = {
+    /**
+     * The label to be used in the GUI
+     */
+    display: string;
+    /**
+     * The field this facet should apply to.
+     *
+     * In most cases it should be the property name of the model. Something like:
+     *
+     * - name
+     * - description
+     * - artist.name
+     */
+    field: string;
+    /**
+     * This is required only if there are duplicated `field` in all facets.
+     *
+     * If `name` exists it will be used as an alternative identifier for facet, instead of `field`, to match
+     * a selection with its facet (in `getFacetFromSelection()`). So a selection must be given with the `name`,
+     * instead of `field`. And it will also be present in the URL. But it will never appear in the GraphQL selection.
+     *
+     * https://github.com/Ecodev/natural-search/issues/16
+     */
+    name?: string;
+    /**
+     * A function to transform the selection before it is applied onto the filter.
+     *
+     * This would typically be useful to do unit conversion so the GUI has some user
+     * friendly values, but the API works with a "low-level" unit.
+     */
+    transform?: (s: NaturalSearchSelection) => NaturalSearchSelection;
+};
+/**
+ * Facet that is only a flag (set or unset)
+ */
+export type FlagFacet<Condition> = {
+    /**
+     * The value to be returned when the flag is set
+     */
+    condition: Condition;
+    /**
+     * If true the value is set when the flag does NOT exist and the
+     * value is unset when the flag exists.
+     *
+     * Defaults to `false`.
+     */
+    inversed?: boolean;
+} & BasicFacet;
+/**
+ * Facet that uses a component in a dropdown
+ */
+export type DropdownFacet<C> = {
+    component: Type<DropdownComponent>;
+    /**
+     * Show a button into the dropdown container to validate value. Gives alternative to "click out" and incoming "tab/esc" key.
+     */
+    showValidateButton?: boolean;
+    /**
+     * Anything that could be useful for the dropdown component
+     */
+    configuration?: C;
+} & BasicFacet;
+/**
+ * A facet
+ */
+export type Facet = DropdownFacet<any> | FlagFacet<any>;
+/**
+ * Exhaustive list of facets
+ */
+export type NaturalSearchFacets = Facet[];
+export {};

package/vanilla/src/lib/modules/search/types/values.d.ts

@@ -0,0 +1,32 @@
+import { FilterGroupConditionField } from '../classes/graphql-doctrine.types';
+import { Facet } from './facet';
+/**
+ * Type for a search selection
+ */
+export type NaturalSearchSelection = {
+    field: string;
+    /**
+     * This is required if the facet also have a `name`.
+     *
+     * See BasicFacet.name
+     */
+    name?: string;
+    condition: FilterGroupConditionField;
+};
+/**
+ * Groups are a list of values, that should be interpreted with AND condition
+ */
+export type GroupSelections = NaturalSearchSelection[];
+/**
+ * List of groups, that should be interpreted with OR condition
+ * Final input / output format
+ */
+export type NaturalSearchSelections = GroupSelections[];
+/**
+ * Consolidated type for a selection and it's matching facet
+ * Used internally for dropdown
+ */
+export type DropdownResult = {
+    condition: FilterGroupConditionField;
+    facet?: Facet;
+};

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;
+}