xdbc 1.0.211 → 1.0.213

package/dist/DBC.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Provides a **D**esign **B**y **C**ontract Framework using decorators.
+ *
+ * @remarks
+ * Maintainer: Callari, Salvatore (XDBC@WaXCode.net) */
+export declare class DBC {
+    private static readonly MAX_CACHE_SIZE;
+    private static dbcCache;
+    private static pathTokenCache;
+    /** Evicts the oldest entry if the cache exceeds the maximum size. */
+    private static evictIfNeeded;
+    private static getHost;
+    private static getDBC;
+    /** Stores all request for parameter values registered by {@link decPrecondition }. */
+    static paramValueRequests: Map<string, Map<number, Array<(value: any) => undefined>>>;
+    /**
+     * Generate a unique key for storing parameter value requests.
+     * Format: "ClassName:methodName"
+     */
+    private static getRequestKey;
+    /**
+     * Make a request to get the value of a certain parameter of specific method in a specific {@link object }.
+     * That request gets enlisted in {@link paramValueRequests } which is used by {@link ParamvalueProvider} to invoke the
+     * given "receptor" with the parameter value stored in there. Thus a parameter decorator using this method will
+     * not receive any value of the top method is not tagged with {@link ParamvalueProvider}.
+     *
+     * @param target		The {@link object } containing the method with the parameter which's value is requested.
+     * @param methodName	The name of the method with the parameter which's value is requested.
+     * @param index			The index of the parameter which's value is requested.
+     * @param receptor		The method the requested parameter-value shall be passed to when it becomes available. */
+    protected static requestParamValue(target: object, methodName: string | symbol, index: number, receptor: (value: any) => undefined): undefined;
+    /**
+     * A decorator usable on both **methods** (including setters) and **classes**.
+     *
+     * - **On a method**: wraps the method so that any {@link DBC } preconditions registered on its parameters
+     *   via XDBC parameter-decorator factories are dispatched with the actual argument values on each call.
+     * - **On a class**: wraps the constructor so that preconditions registered on constructor parameters are
+     *   dispatched **before** the original constructor body runs, upholding true precondition semantics.
+     *
+     * In both cases the "receptor" callbacks enlisted in {@link paramValueRequests } by {@link requestParamValue }
+     * are invoked with the live argument values.
+     *
+     * @param targetOrConstructor	When used as a **method** decorator: the {@link object } hosting the tagged method.
+     * 								When used as a **class** decorator: the class constructor.
+     * @param propertyKey 			*(method decorator only)* The tagged method's name as provided by the runtime.
+     * @param descriptor 			*(method decorator only)* The {@link PropertyDescriptor } as provided by the runtime.
+     *
+     * @returns 	When used as a **method** decorator: the (modified) {@link PropertyDescriptor }.
+     * 				When used as a **class** decorator: a replacement constructor that performs precondition checks. */
+    static ParamvalueProvider(target: object, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor;
+    static ParamvalueProvider<T extends new (...args: any[]) => any>(constructor: T): T;
+    /**
+     * A property-decorator factory serving as a **D**esign **B**y **C**ontract Invariant.
+     * This invariant aims to check the instance of the class not the value to be get or set.
+     *
+     * @param contracts The {@link DBC }-Contracts the value shall uphold.
+     *
+     * @throws 	A {@link DBC.Infringement } whenever the property is tried to be get or set without the instance of it's class
+     * 			fulfilling the specified **contracts**. */
+    static decClassInvariant(contracts: Array<{
+        check: (toCheck: unknown | null | undefined) => boolean | string;
+    }>, path?: string | undefined, dbc?: string): (target: unknown, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+    /**
+     * A property-decorator factory serving as a **D**esign **B**y **C**ontract Invariant.
+     * Since the value must be initialized or set according to the specified **contracts** the value will only be checked
+     * when assigning it.
+     *
+     * @param contracts The {@link DBC }-Contracts the value shall uphold.
+     *
+     * @throws 	A {@link DBC.Infringement } whenever the property is tried to be set to a value that does not comply to the
+     * 			specified **contracts**, by the returned method.*/
+    static decInvariant(contracts: Array<{
+        check: (toCheck: unknown | null | undefined) => boolean | string;
+    }>, path?: string | undefined, dbc?: string | undefined, hint?: string | undefined): (target: unknown, propertyKey: string | symbol) => void;
+    /**
+     * A method decorator factory checking the result of a method whenever it is invoked thus also usable on getters.
+     *
+     * @param check	The **(toCheck: any, object, string) => boolean | string** to use for checking.
+     * @param dbc	See {@link DBC.resolveDBCPath }.
+     * @param path	The dotted path referring to the actual value to check, starting form the specified one.
+     *
+     * @returns The **( target : object, propertyKey : string, descriptor : PropertyDescriptor ) : PropertyDescriptor**
+     * 			invoked by Typescript.
+     */
+    static decPostcondition(check: (toCheck: any, target: object, propertyKey: string) => boolean | string, dbc?: string | undefined, path?: string | undefined, hint?: string | undefined): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+    /**
+     * A parameter-decorator factory that requests the tagged parameter's value passing it to the provided
+     * "check"-method when the value becomes available.
+     *
+     * @param check	The "( unknown ) => void" to be invoked along with the tagged parameter's value as soon
+     * 				as it becomes available.
+     * @param dbc  	See {@link DBC.resolveDBCPath }.
+     * @param path	The dotted path referring to the actual value to check, starting form the specified one.
+     * 				May contain :: to separate multiple paths.
+     *
+     * @returns The **(target: object, methodName: string | symbol, parameterIndex: number ) => void** invoked by Typescript- */
+    protected static decPrecondition(check: (value: unknown, target: object, methodName: string | symbol, parameterIndex: number) => boolean | string, dbc?: string | undefined, path?: string | undefined, hint?: string | undefined): (target: object, methodName: string | symbol, parameterIndex: number) => void;
+    /**
+     * Creates a PRE decorator from a checkAlgorithm function and its bound arguments.
+     * Reduces boilerplate across contract classes.
+     *
+     * @param checkFn  A function that takes (value, ...boundArgs) and returns true or an error string.
+     * @param boundArgs The arguments to bind to the check function after the value.
+     * @param dbc      See {@link DBC.decPrecondition}.
+     * @param path     See {@link DBC.decPrecondition}.
+     * @param hint     See {@link DBC.decPrecondition}.
+     */
+    static createPRE(checkFn: (...args: any[]) => boolean | string, boundArgs: any[], dbc?: string, path?: string, hint?: string): (target: object, methodName: string | symbol, parameterIndex: number) => void;
+    /**
+     * Creates a POST decorator from a checkAlgorithm function and its bound arguments.
+     *
+     * @param checkFn  A function that takes (value, ...boundArgs) and returns true or an error string.
+     * @param boundArgs The arguments to bind to the check function after the value.
+     * @param dbc      See {@link DBC.decPostcondition}.
+     * @param path     See {@link DBC.decPostcondition}.
+     * @param hint     See {@link DBC.decPostcondition}.
+     */
+    static createPOST(checkFn: (...args: any[]) => boolean | string, boundArgs: any[], dbc?: string, path?: string, hint?: string): (target: object, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+    /**
+     * Creates an INVARIANT decorator from a contract constructor and its bound arguments.
+     *
+     * @param ContractClass A class with a constructor that produces an object with a `check` method.
+     * @param ctorArgs      The arguments to pass to the contract constructor.
+     * @param dbc           See {@link DBC.decInvariant}.
+     * @param path          See {@link DBC.decInvariant}.
+     * @param hint          See {@link DBC.decInvariant}.
+     */
+    static createINVARIANT(ContractClass: new (...args: any[]) => {
+        check: (toCheck: unknown | null | undefined) => boolean | string;
+    }, ctorArgs: any[], dbc?: string, path?: string, hint?: string): (target: unknown, propertyKey: string | symbol) => void;
+    /** Stores settings concerning the execution of checks. */
+    executionSettings: {
+        checkPreconditions: boolean;
+        checkPostconditions: boolean;
+        checkInvariants: boolean;
+    };
+    /** Stores settings concerning warnings. */
+    warningSettings: {
+        logToConsole: boolean;
+    };
+    /**
+     * Reports a warning.
+     *
+     * @param message The message containing the warning. */
+    protected reportWarning(message: string): undefined;
+    /** Stores the settings concerning infringements */
+    infringementSettings: {
+        throwException: boolean;
+        logToConsole: boolean;
+    };
+    /** Sanitizes a value for safe inclusion in error messages. */
+    private static sanitize;
+    /**
+     * Reports an infringement according to the {@link infringementSettings } also generating a proper {@link string }-wrapper
+     * for the given "message" & violator.
+     *
+     * @param message	The {@link string } describing the infringement and it's provenience.
+     * @param violator 	The {@link string } describing or naming the violator. */
+    protected reportInfringement(message: string, violator: string, target: object, value: unknown, path: string | undefined, hint?: string | undefined): undefined;
+    /**
+     * Reports a parameter-infringement via {@link reportInfringement } also generating a proper {@link string }-wrapper
+     * for the given "message","method", parameter-"index" & value.
+     *
+     * @param message	The {@link string } describing the infringement and it's provenience.
+     * @param method 	The {@link string } describing or naming the violator.
+     * @param index		The index of the parameter within the argument listing.
+     * @param value 	The parameter's value. */
+    reportParameterInfringement(message: string, target: object, path: string | undefined, method: string, index: number, value: unknown, hint?: string | undefined): undefined;
+    /**
+     * Reports a field-infringement via {@link reportInfringement } also generating a proper {@link string }-wrapper
+     * for the given **message** & **name**.
+     *
+     * @param message	A {@link string } describing the infringement and it's provenience.
+     * @param key 		The property key.
+     * @param path		The dotted-path {@link string } that leads to the value not fulfilling the contract starting from
+     * 					the tagged one.
+     * @param value		The value not fulfilling a contract. */
+    reportFieldInfringement(message: string, target: object, path: string | undefined, key: string, value: unknown, hint?: string | undefined): undefined;
+    /**
+     * Reports a returnvalue-infringement according via {@link reportInfringement } also generating a proper {@link string }-wrapper
+     * for the given "message","method" & value.
+     *
+     * @param message	The {@link string } describing the infringement and it's provenience.
+     * @param method 	The {@link string } describing or naming the violator.
+     * @param value		The parameter's value. */
+    reportReturnvalueInfringement(message: string, target: object, path: string | undefined, method: string, value: any, hint?: string | undefined): void;
+    /** An {@link Error } to be thrown whenever an infringement is detected. */
+    static Infringement: {
+        new (message: string): {
+            name: string;
+            message: string;
+            stack?: string;
+        };
+    };
+    /**
+     * Resolves the specified dotted {@link string }-path to a {@link DBC }.
+     *
+     * @param obj 	The {@link object } to start resolving from.
+     * @param path 	The dotted {@link string }-path leading to the {@link DBC }.
+     *
+     * @returns The requested {@link DBC }.
+     */
+    static resolveDBCPath: (obj: any, path: string) => DBC;
+    /**
+     * Constructs this {@link DBC } without mounting it on the global namespace.
+     * Use {@link DBC.register } to make the instance available at a specific path on globalThis.
+     *
+     * @param infringementSettings 	See {@link DBC.infringementSettings }.
+     * @param executionSettings		See {@link DBC.executionSettings }. */
+    constructor(infringementSettings?: {
+        throwException: boolean;
+        logToConsole: boolean;
+    }, executionSettings?: {
+        checkPreconditions: boolean;
+        checkPostconditions: boolean;
+        checkInvariants: boolean;
+    });
+    /**
+     * Registers a {@link DBC } instance at the specified dotted path on globalThis (or window),
+     * making it available for decorator resolution via string paths.
+     *
+     * @param instance	The {@link DBC } instance to register.
+     * @param path		The dotted path to register at (default: `"WaXCode.DBC"`). */
+    static register(instance: DBC, path?: string): void;
+    /**
+     * Executes a callback with an isolated {@link DBC } instance temporarily registered at the default path.
+     * The previous instance (if any) is restored after the callback completes — even if it throws.
+     * Useful for test isolation.
+     *
+     * @param fn The callback receiving the isolated {@link DBC } instance. */
+    static isolated(fn: (dbc: DBC) => void): void;
+    /**
+     * Resolves the desired {@link object } out a given one **toResolveFrom** using the specified **path**.
+     *
+     * @param toResolveFrom The {@link object } starting to resolve from.
+     * @param path			The dotted path-{@link string }.
+     * 						This string uses ., [...], and () to represent accessing nested properties,
+     * 						array elements/object keys, and calling methods, respectively, mimicking JavaScript syntax to navigate
+     * 						an object's structure. Code, e.g. something like a.b( 1 as number ).c, will not be executed and
+     * 						thus make the retrieval fail.
+     *
+     * @returns The requested {@link object }, NULL or UNDEFINED. */
+    static resolve(toResolveFrom: unknown, path: string): any;
+}

package/dist/Demo.d.ts

@@ -0,0 +1,20 @@
+/** Demonstrative use of **D**esign **B**y **C**ontract Decorators */
+export declare class Demo {
+    testProperty: string;
+    testParamvalueAndReturnvalue(a: string): string;
+    testReturnvalue(a: string): string;
+    testEQAndPath(o: HTMLElement): void;
+    testEQAndPathWithInversion(o: HTMLElement): void;
+    testTYPE(o: unknown): void;
+    testAE(x: Array<unknown>): void;
+    testREGEXWithAE(x: Array<string>): void;
+    testINSTANCE(candidate: any): undefined;
+    testAERange(x: Array<unknown>): void;
+    testAEIndex(x: Array<unknown>): void;
+    testGREATER(input: number): void;
+    testGREATER_OR_EQUAL(input: number): void;
+    testLESS(input: number): void;
+    testLESS_OR_EQUAL(input: number): void;
+    testDIFFERENT(input: number): void;
+    static testStaticMethod(message: string, count: number): string;
+}