@webda/core 2.4.1 → 3.0.0

package/lib/models/coremodel.d.ts

@@ -1,45 +1,32 @@
+import { JSONSchema7 } from "json-schema";
+import { ModelGraph, ModelsTree } from "../application.js";
 import { Core } from "../core.js";
 import { Service } from "../services/service.js";
 import { Store } from "../stores/store.js";
-import { Context, OperationContext } from "../utils/context.js";
+import { OperationContext } from "../utils/context.js";
 import { HttpMethodType } from "../utils/httpcontext.js";
-type ModelLoader<T> = {
-    refresh: () => Promise<T>;
-    getUuid(): string;
-};
-type ModelLinker<T> = string & ModelLoader<T>;
-/**
- * Load related objects
- */
-export type ModelLinked<T> = (query?: string) => Promise<T[]>;
-/**
- * Mapper attribute (target of a Mapper service)
- */
-export type ModelMapper<T, K extends keyof T> = Pick<T, K> & ModelLoader<T>;
+import { ModelActions, RawModel } from "./relations.js";
 /**
- * Define a ModelMap attribute
- */
-export type ModelMappers<T, _FK extends keyof T, K extends keyof T> = ModelMapper<T, K>[];
-/**
- * Define a link to 1:n relation
- */
-export type ModelLink<T, _FK extends keyof T = any> = ModelLinker<T>;
-/**
- * Define several links for n:m relation
+ * Expose the model through API or GraphQL if it exists
+ * The model will be exposed using its class name + 's'
+ * If you need to have a specific plural, use the annotation WebdaPlural
+ *  to define the plural name
+ *
+ * @returns
  */
-export type ModelLinks<T, _FK extends keyof T> = ModelLinker<T>[] | {
-    [key: string]: ModelLinker<T>;
-};
+export declare function Expose(params?: Partial<ExposeParameters>): (target: CoreModelDefinition) => void;
 /**
- * Define the parent of the model
+ * Filter type keys by type
  */
-export type ModelParent<T> = ModelLink<T, any>;
+export type FilterKeys<T extends CoreModel, K> = {
+    [L in keyof T]: T[L] extends K ? L : never;
+}[keyof T];
 /**
- * Define an export of actions from Model
+ * Define an Action on a model
+ *
+ * It is basically a method designed to be called by the API or external
+ * systems
  */
-export type ModelActions = {
-    [key: string]: ModelAction;
-};
 export interface ModelAction {
     /**
      * Method for the route
@@ -59,8 +46,58 @@ export interface ModelAction {
      */
     openapi?: any;
 }
+/**
+ * Expose parameters for the model
+ */
+export interface ExposeParameters {
+    /**
+     * If model have parent but you still want it to be exposed as root
+     * in domain-like service: DomainService, GraphQL
+     *
+     * It would create alias for the model in the root too
+     */
+    root?: boolean;
+    /**
+     * You can select to not expose some methods like create, update, delete, get, query
+     */
+    restrict: {
+        /**
+         * Create a new object
+         */
+        create?: boolean;
+        /**
+         * Update an existing object
+         *
+         * Includes PUT and PATCH
+         */
+        update?: boolean;
+        /**
+         * Query the object
+         */
+        query?: boolean;
+        /**
+         * Get a single object
+         */
+        get?: boolean;
+        /**
+         * Delete an object
+         */
+        delete?: boolean;
+        /**
+         * Do not create operations for the model
+         */
+        operation?: boolean;
+    };
+}
+/**
+ *
+ */
 export interface CoreModelDefinition<T extends CoreModel = CoreModel> {
     new (): T;
+    /**
+     * If the model have some Expose annotation
+     */
+    Expose?: ExposeParameters;
     /**
      * Create a CoreModel object loaded with the content of object
      *
@@ -70,28 +107,73 @@ export interface CoreModelDefinition<T extends CoreModel = CoreModel> {
      * @param object to load data from
      * @param context if the data is unsafe from http
      */
-    factory(model: new () => T, object: any, context?: Context): T;
+    factory(model: new () => T, object: any, context?: OperationContext): T;
+    /**
+     * Get the model actions
+     */
     getActions(): {
         [key: string]: ModelAction;
     };
+    /**
+     * Get the model store
+     */
+    store(): Store<T>;
+    /**
+     * Get the model schema
+     */
+    getSchema(): JSONSchema7;
+    /**
+     * Get the model hierarchy
+     */
+    getHierarchy(): {
+        ancestors: string[];
+        children: ModelsTree;
+    };
+    /**
+     * Get the model relations
+     */
+    getRelations(): ModelGraph;
+    /**
+     * Get Model identifier
+     */
+    getIdentifier(short?: boolean): string;
+    /**
+     * Complete uuid useful to implement uuid prefix or suffix
+     * @param uid
+     */
+    completeUid(uid: string): string;
+    /**
+     * Get the model uuid field if you do not want to use the uuid field
+     */
     getUuidField(): string;
-    getLastUpdateField(): string;
-    getCreationField(): string;
-    getPermissionQuery(context?: Context): null | {
+    /**
+     * Permission query for the model
+     * @param context
+     */
+    getPermissionQuery(context?: OperationContext): null | {
         partial: boolean;
         query: string;
     };
+    /**
+     * Reference to an object without doing a DB request yet
+     */
+    ref: typeof CoreModel.ref;
+    /**
+     * Create a new model
+     * @param this
+     * @param data
+     */
+    create<T extends CoreModel>(this: Constructor<T>, data: RawModel<T>): Promise<T>;
+    /**
+     * Query the model
+     * @param query
+     */
+    query(query?: string, includeSubclass?: boolean, context?: OperationContext): Promise<{
+        results: T[];
+        continuationToken?: string;
+    }>;
 }
-export type Constructor<T> = new (...args: any[]) => T;
-/**
- * Sent if action required attached CoreModel is trigger
- * A Model cannot be detached anymore
- *
- * @deprecated
- */
-export declare class CoreModelUnattachedError extends Error {
-    constructor();
-}
+export type Constructor<T, K extends Array<any> = []> = new (...args: K) => T;
 /**
  * Make a property hidden from json
  * @param target
@@ -107,6 +189,56 @@ export declare function Action(options?: {
     methods?: HttpMethodType[];
     openapi?: any;
 }): (target: any, propertyKey: string) => void;
+export declare class ModelRef<T extends CoreModel> {
+    protected uuid: string;
+    protected store: Store<T>;
+    protected model: CoreModelDefinition<T>;
+    constructor(uuid: string, model: CoreModelDefinition<T>);
+    get(): Promise<T>;
+    set(id: string | T): void;
+    toString(): string;
+    toJSON(): string;
+    getUuid(): string;
+    deleteItemFromCollection(prop: FilterKeys<T, any[]>, index: number, itemWriteCondition: any, itemWriteConditionField?: string): Promise<void>;
+    upsertItemToCollection(prop: FilterKeys<T, any[]>, item: any, index?: number, itemWriteCondition?: any, itemWriteConditionField?: string): Promise<void>;
+    exists(): Promise<boolean>;
+    delete(): Promise<void>;
+    conditionalPatch(updates: Partial<T>, conditionField: any, condition: any): Promise<boolean>;
+    patch(updates: Partial<T>): Promise<boolean>;
+    setAttribute(attribute: keyof T, value: any): Promise<void>;
+    removeAttribute(attribute: keyof T, itemWriteCondition?: any, itemWriteConditionField?: keyof T): Promise<void>;
+    incrementAttributes(info: {
+        property: FilterKeys<T, number>;
+        value: number;
+    }[]): Promise<any[]>;
+}
+export declare class ModelRefWithCreate<T extends CoreModel> extends ModelRef<T> {
+    /**
+     * Allow to create a model
+     * @param defaultValue
+     * @param context
+     * @param withSave
+     * @returns
+     */
+    create(defaultValue: RawModel<T>, context?: OperationContext, withSave?: boolean): Promise<T>;
+    /**
+     * Load a model from the known store
+     *
+     * @param this the class from which the static is called
+     * @param id of the object to load
+     * @param defaultValue if object not found return a default object
+     * @param context to set on the object
+     * @returns
+     */
+    getOrCreate(defaultValue: RawModel<T>, context?: OperationContext, withSave?: boolean): Promise<T>;
+}
+export declare class ModelRefCustom<T extends CoreModel> extends ModelRef<T> {
+    uuid: string;
+    constructor(uuid: string, model: CoreModelDefinition<T>, data: any);
+    toJSON(): any;
+    getUuid(): string;
+}
+export type ModelRefCustomProperties<T extends CoreModel, K> = ModelRefCustom<T> & K;
 /**
  * Basic Object in Webda
  *
@@ -121,11 +253,15 @@ declare class CoreModel {
     /**
      * Class reference to the object
      */
-    __class: any;
+    __class: CoreModelDefinition;
     /**
      * Type name
      */
     __type: string;
+    /**
+     * Types name
+     */
+    __types: string[];
     /**
      * Object context
      *
@@ -154,12 +290,66 @@ declare class CoreModel {
      */
     __deleted: boolean;
     constructor();
+    /**
+     *
+     * @returns
+     */
+    static getRelations(): ModelGraph;
     /**
      * Get Store for this model
      * @param this
      * @returns
      */
     static store<T extends CoreModel>(this: Constructor<T>): Store<T>;
+    /**
+     * Complete the uid with prefix if any
+     *
+     * Useful when object are stored with a prefix for full uuid
+     * @param uid
+     * @returns
+     */
+    static completeUid(uid: string): string;
+    /**
+     * Return the known schema
+     * @returns
+     */
+    static getSchema(): JSONSchema7;
+    /**
+     * Get a reference to a model
+     * @param this
+     * @param uid
+     * @returns
+     */
+    static ref<T extends CoreModel>(this: Constructor<T>, uid: string): ModelRefWithCreate<T>;
+    /**
+     * Get a reference to a model
+     * @param this
+     * @param uid
+     * @returns
+     */
+    static create<T extends CoreModel>(this: Constructor<T>, data: RawModel<T>): Promise<T>;
+    /**
+     * Get identifier for this model
+     * @returns
+     */
+    static getIdentifier(short?: boolean): string;
+    /**
+     * Get the model hierarchy
+     *
+     * Ancestors will contain every model it inherits from
+     * Children will contain every model that inherits from this model in a tree structure
+     */
+    static getHierarchy(): {
+        ancestors: string[];
+        children: ModelsTree;
+    };
+    /**
+     * Unflat an object
+     * @param data
+     * @param split
+     * @returns
+     */
+    static unflat<T = any>(data: any, split?: string): T;
     /**
      * Create subobject for a model
      *
@@ -169,13 +359,36 @@ declare class CoreModel {
      * @returns
      */
     unflat<T>(split?: string): T;
+    /**
+     * Flat an object into another
+     *
+     * {
+     *    a: {
+     *      b: 1
+     *    },
+     *    c: 1
+     * }
+     *
+     * become
+     *
+     * {
+     *    "a#b": 1
+     *    "c": 1
+     * }
+     *
+     * @param target
+     * @param data
+     * @param split
+     * @param prefix
+     */
+    static flat(target: any, data: any, split?: string, prefix?: string): any;
     /**
      * Query for models
      * @param this
      * @param id
      * @returns
      */
-    static query<T extends CoreModel>(this: Constructor<T>, query: string): Promise<{
+    static query<T extends CoreModel>(this: Constructor<T>, query?: string, includeSubclass?: boolean, context?: OperationContext): Promise<{
         results: T[];
         continuationToken?: string;
     }>;
@@ -212,27 +425,20 @@ declare class CoreModel {
      * @param context of the query
      * @returns
      */
-    static getPermissionQuery(_ctx: Context): null | {
+    static getPermissionQuery(_ctx: OperationContext): null | {
         partial: boolean;
         query: string;
     };
+    checkAct(context: OperationContext, action: "create" | "update" | "get" | "delete" | "get_binary" | "detach_binary" | "attach_binary" | "update_binary_metadata" | "subscribe" | string): Promise<void>;
     /**
      * By default nothing is permitted on a CoreModel
      * @returns
      */
-    canAct(_ctx: Context, _action: "create" | "update" | "get" | "delete" | "get_binary" | "detach_binary" | "attach_binary" | "update_binary_metadata" | "subscribe" | string): Promise<this>;
+    canAct(_context: OperationContext, _action: "create" | "update" | "get" | "delete" | "get_binary" | "detach_binary" | "attach_binary" | "update_binary_metadata" | "subscribe" | string): Promise<string | boolean>;
     /**
      * Get the UUID property
      */
     static getUuidField(): string;
-    /**
-     * Get the UUID property
-     */
-    static getLastUpdateField(): string;
-    /**
-     * Get the UUID property
-     */
-    static getCreationField(): string;
     /**
      * Create an object
      * @returns
@@ -244,16 +450,6 @@ declare class CoreModel {
      * @returns
      */
     static instanceOf(object: any): boolean;
-    /**
-     * Return if an object is attached to its store
-     * @deprecated Will be removed in 3.0
-     */
-    isAttached(): boolean;
-    /**
-     * Attach an object to a store instance
-     * @deprecated Will be removed in 3.0
-     */
-    attach(store: Store<this>): this;
     /**
      * Return a unique reference within the application to the object
      *
@@ -268,16 +464,7 @@ declare class CoreModel {
      * @param partials
      * @returns
      */
-    static fromFullUuid<T extends CoreModel = CoreModel>(core: Core, fullUuid: string, partials?: any): Promise<T>;
-    /**
-     * Remove all the attribute starting with __
-     * @param key
-     * @param value
-     * @returns
-     *
-     * @deprecated
-     */
-    _jsonFilter(key: any, value: any): any;
+    static fromFullUuid<T extends CoreModel = CoreModel>(fullUuid: string, core?: Core, partials?: any): Promise<T>;
     /**
      * Allow to define custom permission per attribute
      *
@@ -297,7 +484,12 @@ declare class CoreModel {
      * @param raw data
      * @param secure if false will ignore any _ variable
      */
-    load(raw: Partial<this>, secure?: boolean): this;
+    load(raw: RawModel<this>, secure?: boolean): this;
+    /**
+     * Patch every attribute that is based on a relation
+     * to add all the helpers
+     */
+    protected handleRelations(): void;
     /**
      * Context of the request
      */
@@ -329,23 +521,13 @@ declare class CoreModel {
      * @throws Error if the object is not coming from a store
      */
     delete(): Promise<void>;
-    /**
-     * Load a model from the known store
-     *
-     * @param this the class from which the static is called
-     * @param id of the object to load
-     * @param defaultValue if object not found return a default object
-     * @param context to set on the object
-     * @returns
-     */
-    static get<T>(this: Constructor<T>, id: string, defaultValue?: Partial<T>, context?: OperationContext): Promise<T>;
     /**
      * Patch current object with this update
      * @param obj
      * @param conditionField if null no condition used otherwise fallback to lastUpdate
      * @param conditionValue
      */
-    patch(obj: Partial<this>, conditionField?: string | null, conditionValue?: any): Promise<void>;
+    patch(obj: Partial<this>, conditionField?: keyof this | null, conditionValue?: any): Promise<void>;
     /**
      * Save this object
      *
@@ -358,7 +540,7 @@ declare class CoreModel {
      * @param ctx
      * @param updates
      */
-    validate(ctx: Context, updates: any, ignoreRequired?: boolean): Promise<boolean>;
+    validate(ctx: OperationContext, updates: any, ignoreRequired?: boolean): Promise<boolean>;
     /**
      * Generate uuid for the object
      *
@@ -426,4 +608,14 @@ declare class CoreModel {
      */
     _onUpdated(): Promise<void>;
 }
-export { CoreModel };
+/**
+ * CoreModel with a uuid
+ */
+declare class UuidModel extends CoreModel {
+    uuid: string;
+    /**
+     * @override
+     */
+    validate(ctx: OperationContext<any, any>, updates: any, ignoreRequired?: boolean): Promise<boolean>;
+}
+export { CoreModel, UuidModel };