@aidc-toolkit/app-extension 0.9.19-beta

package/src/types.ts

@@ -0,0 +1,144 @@
+/**
+ * Type that error type is expected to extend. If the application framework reports errors through the throw/catch
+ * mechanism, the error type is expected to extend {@link Error}. Otherwise, it may extend any object type.
+ *
+ * @template ThrowError
+ * If true, errors are reported through the throw/catch mechanism.
+ */
+export type ErrorExtends<ThrowError extends boolean> = ThrowError extends true ? Error : object;
+
+/**
+ * Sheet.
+ */
+export interface Sheet {
+    /**
+     * Sheet name.
+     */
+    readonly name: string;
+}
+
+/**
+ * Single cell address.
+ */
+export interface Address {
+    /**
+     * Zero-indexed row.
+     */
+    readonly rowIndex: number;
+
+    /**
+     * Zero-indexed column.
+     */
+    readonly columnIndex: number;
+}
+
+/**
+ * Sheet address.
+ */
+export interface SheetAddress extends Sheet, Address {
+}
+
+/**
+ * Range of cells.
+ */
+export interface Range {
+    /**
+     * Start address, inclusive.
+     */
+    readonly startAddress: Address;
+
+    /**
+     * End address, exclusive.
+     */
+    readonly endAddress: Address;
+}
+
+/**
+ * Sheet range.
+ */
+export interface SheetRange extends Sheet, Range {
+}
+
+/**
+ * Matrix type; shorthand for defining a two-dimensional matrix (array of array) of a type.
+ *
+ * @template T
+ * Type.
+ */
+export type Matrix<T> = T[][];
+
+/**
+ * Function result, possibly including an error result. If the application framework reports errors through the return
+ * value, the result is the union of the result type and the error type; otherwise, it's just the result type.
+ *
+ * @template TResult
+ * Result type.
+ *
+ * @template ThrowError
+ * If true, errors are reported through the throw/catch mechanism.
+ *
+ * @template TError
+ * Error type.
+ */
+export type ResultError<TResult, ThrowError extends boolean, TError extends ErrorExtends<ThrowError>> = ThrowError extends false ? TResult | TError : TResult;
+
+/**
+ * Function result as matrix, possibly including an error result in each element. If the application framework reports
+ * errors through the return value, the individual element result is the union of the result type and the error type;
+ * otherwise, it's just the result type.
+ *
+ * @template TResult
+ * Result type.
+ *
+ * @template ThrowError
+ * If true, errors are reported through the throw/catch mechanism.
+ *
+ * @template TError
+ * Error type.
+ */
+export type MatrixResultError<TResult, ThrowError extends boolean, TError extends ErrorExtends<ThrowError>> = Matrix<ResultError<TResult, ThrowError, TError>>;
+
+/**
+ * Typed function, applicable to any function, stricter than {@link Function}.
+ */
+export type TypedFunction<TMethod extends (...args: Parameters<TMethod>) => ReturnType<TMethod>> = (...args: Parameters<TMethod>) => ReturnType<TMethod>;
+
+/**
+ * Typed synchronous function, applicable to any function that doesn't return a Promise.
+ */
+export type TypedSyncFunction<TMethod extends TypedFunction<TMethod>> = [ReturnType<TMethod>] extends [PromiseLike<unknown>] ? never : TypedFunction<TMethod>;
+
+/**
+ * Determine the fundamental promised type. This is stricter than `Awaited\<Type\>` in that it requires a Promise.
+ */
+type PromisedType<T> = [T] extends [PromiseLike<infer TPromised>] ? TPromised : never;
+
+/**
+ * Typed asynchronous function, applicable to any function that returns a Promise.
+ */
+export type TypedAsyncFunction<TMethod extends (...args: Parameters<TMethod>) => PromiseLike<PromisedType<ReturnType<TMethod>>>> = (...args: Parameters<TMethod>) => Promise<PromisedType<ReturnType<TMethod>>>;
+
+/**
+ * Nullishable type. Application extension may pass `null` or `undefined` to missing parameters.
+ */
+export type Nullishable<T> = T | null | undefined;
+
+/**
+ * Non-nullishable type. If T is an object type, it is spread and attributes within it are made non-nullishable.
+ */
+export type NonNullishable<T> = T extends object ? {
+    [P in keyof T]-?: NonNullishable<T[P]>
+} : NonNullable<T>;
+
+/**
+ * Determine if argument is nullish. Application extension may pass `null` or `undefined` to missing parameters.
+ *
+ * @param argument
+ * Argument.
+ *
+ * @returns
+ * True if argument is undefined or null.
+ */
+export function isNullish<T>(argument: T | null | undefined): argument is null | undefined {
+    return argument === null || argument === undefined;
+}

package/src/utility/character-set-descriptor.ts

@@ -0,0 +1,32 @@
+import { type ParameterDescriptor, Type } from "../descriptor.js";
+
+const exclusionParameterDescriptor: ParameterDescriptor = {
+    name: "exclusion",
+    type: Type.Number,
+    isMatrix: false,
+    isRequired: false
+};
+
+export const exclusionNoneParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: exclusionParameterDescriptor,
+    sortOrder: 0,
+    name: "exclusionNone"
+};
+
+export const exclusionFirstZeroParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: exclusionParameterDescriptor,
+    sortOrder: 1,
+    name: "exclusionFirstZero"
+};
+
+export const exclusionAllNumericParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: exclusionParameterDescriptor,
+    sortOrder: 2,
+    name: "exclusionAllNumeric"
+};
+
+export const exclusionAnyParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: exclusionParameterDescriptor,
+    sortOrder: 3,
+    name: "exclusionAny"
+};

package/src/utility/character-set-proxy.ts

@@ -0,0 +1,185 @@
+import {
+    ALPHABETIC_CREATOR,
+    ALPHANUMERIC_CREATOR,
+    type CharacterSetCreator,
+    type CharacterSetValidation,
+    type Exclusion,
+    HEXADECIMAL_CREATOR,
+    NUMERIC_CREATOR,
+    Sequence
+} from "@aidc-toolkit/utility";
+import type { AppExtension } from "../app-extension.js";
+import {
+    expandParameterDescriptor,
+    type ParameterDescriptor,
+    ProxyClass,
+    ProxyMethod,
+    ProxyParameter,
+    Type
+} from "../descriptor.js";
+import { LibProxy } from "../lib-proxy.js";
+import type { ErrorExtends, Matrix, MatrixResultError, Nullishable, ResultError } from "../types.js";
+import {
+    exclusionAnyParameterDescriptor,
+    exclusionFirstZeroParameterDescriptor,
+    exclusionNoneParameterDescriptor
+} from "./character-set-descriptor.js";
+import { sParameterDescriptor, validateSParameterDescriptor } from "./string-descriptor.js";
+import { StringProxy } from "./string-proxy.js";
+import {
+    countParameterDescriptor,
+    startValueParameterDescriptor,
+    tweakParameterDescriptor,
+    valueParameterDescriptor
+} from "./transformer-descriptor.js";
+
+const lengthParameterDescriptor: ParameterDescriptor = {
+    name: "length",
+    type: Type.Number,
+    isMatrix: false,
+    isRequired: true
+};
+
+const valueForSParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: sParameterDescriptor,
+    name: "valueForS"
+};
+
+export abstract class CharacterSetProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends StringProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    private readonly _characterSetCreator: CharacterSetCreator;
+
+    protected constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>, characterSetCreator: CharacterSetCreator) {
+        super(appExtension);
+
+        this._characterSetCreator = characterSetCreator;
+    }
+
+    @ProxyMethod({
+        type: Type.String,
+        isMatrix: true
+    })
+    validate(
+        @ProxyParameter(validateSParameterDescriptor) matrixSs: Matrix<string>,
+        @ProxyParameter(exclusionNoneParameterDescriptor) exclusion: Nullishable<Exclusion>
+    ): MatrixResultError<string, ThrowError, TError> {
+        return this.validateString(this._characterSetCreator, matrixSs, {
+            exclusion: exclusion ?? undefined
+        } satisfies CharacterSetValidation);
+    }
+
+    @ProxyMethod({
+        type: Type.Boolean,
+        isMatrix: true
+    })
+    isValid(
+        @ProxyParameter(validateSParameterDescriptor) matrixSs: Matrix<string>,
+        @ProxyParameter(exclusionNoneParameterDescriptor) exclusion: Nullishable<Exclusion>
+    ): MatrixResultError<boolean, ThrowError, TError> {
+        return this.isValidString(this.validate(matrixSs, exclusion));
+    }
+
+    @ProxyMethod({
+        type: Type.String,
+        isMatrix: true
+    })
+    create(
+        @ProxyParameter(lengthParameterDescriptor) length: number,
+        @ProxyParameter(valueParameterDescriptor) matrixValues: Matrix<number | bigint>,
+        @ProxyParameter(exclusionNoneParameterDescriptor) exclusion: Nullishable<Exclusion>,
+        @ProxyParameter(tweakParameterDescriptor) tweak: Nullishable<number | bigint>
+    ): MatrixResultError<string, ThrowError, TError> {
+        const exclusionOrUndefined = exclusion ?? undefined;
+        const tweakOrUndefined = tweak ?? undefined;
+
+        return this.mapMatrix(matrixValues, value => this._characterSetCreator.create(length, value, exclusionOrUndefined, tweakOrUndefined));
+    }
+
+    @ProxyMethod({
+        infixBefore: "Sequence",
+        type: Type.String,
+        isMatrix: true
+    })
+    createSequence(
+        @ProxyParameter(lengthParameterDescriptor) length: number,
+        @ProxyParameter(startValueParameterDescriptor) startValue: number,
+        @ProxyParameter(countParameterDescriptor) count: number,
+        @ProxyParameter(exclusionNoneParameterDescriptor) exclusion: Nullishable<Exclusion>,
+        @ProxyParameter(tweakParameterDescriptor) tweak: Nullishable<number | bigint>
+    ): Matrix<string> {
+        this.appExtension.validateSequenceCount(count);
+
+        const exclusionOrUndefined = exclusion ?? undefined;
+        const tweakOrUndefined = tweak ?? undefined;
+
+        return LibProxy.matrixResult(this._characterSetCreator.create(length, new Sequence(startValue, count), exclusionOrUndefined, tweakOrUndefined));
+    }
+
+    @ProxyMethod({
+        type: Type.Number,
+        isMatrix: true
+    })
+    valueFor(
+        @ProxyParameter(valueForSParameterDescriptor) matrixSs: Matrix<string>,
+        @ProxyParameter(exclusionNoneParameterDescriptor) exclusion: Nullishable<Exclusion>,
+        @ProxyParameter(tweakParameterDescriptor) tweak: Nullishable<number | bigint>
+    ): MatrixResultError<ResultError<TBigInt, ThrowError, TError>, ThrowError, TError> {
+        const exclusionOrUndefined = exclusion ?? undefined;
+        const tweakOrUndefined = tweak ?? undefined;
+
+        return this.mapMatrix(matrixSs, s => this.mapBigInt(this._characterSetCreator.valueFor(s, exclusionOrUndefined, tweakOrUndefined)));
+    }
+}
+
+@ProxyClass({
+    methodInfix: "Numeric",
+    replaceParameterDescriptors: [
+        {
+            name: expandParameterDescriptor(exclusionNoneParameterDescriptor).name,
+            replacement: exclusionFirstZeroParameterDescriptor
+        }
+    ]
+})
+export class NumericProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends CharacterSetProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>) {
+        super(appExtension, NUMERIC_CREATOR);
+    }
+}
+
+@ProxyClass({
+    methodInfix: "Hexadecimal",
+    replaceParameterDescriptors: [
+        {
+            name: expandParameterDescriptor(exclusionNoneParameterDescriptor).name,
+            replacement: exclusionAnyParameterDescriptor
+        }
+    ]
+})
+export class HexadecimalProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends CharacterSetProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>) {
+        super(appExtension, HEXADECIMAL_CREATOR);
+    }
+}
+
+@ProxyClass({
+    methodInfix: "Alphabetic"
+})
+export class AlphabeticProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends CharacterSetProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>) {
+        super(appExtension, ALPHABETIC_CREATOR);
+    }
+}
+
+@ProxyClass({
+    methodInfix: "Alphanumeric",
+    replaceParameterDescriptors: [
+        {
+            name: expandParameterDescriptor(exclusionNoneParameterDescriptor).name,
+            replacement: exclusionAnyParameterDescriptor
+        }
+    ]
+})
+export class AlphanumericProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends CharacterSetProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    constructor(appExtension: AppExtension<ThrowError, TError, TInvocationContext, TBigInt>) {
+        super(appExtension, ALPHANUMERIC_CREATOR);
+    }
+}

package/src/utility/index.ts

@@ -0,0 +1,3 @@
+export * from "./transformer-proxy.js";
+export * from "./reg-exp-proxy.js";
+export * from "./character-set-proxy.js";

package/src/utility/reg-exp-proxy.ts

@@ -0,0 +1,51 @@
+import { RegExpValidator } from "@aidc-toolkit/utility";
+import { type ParameterDescriptor, ProxyClass, ProxyMethod, ProxyParameter, Type } from "../descriptor.js";
+import type { ErrorExtends, Matrix, MatrixResultError, Nullishable } from "../types.js";
+import { validateSParameterDescriptor } from "./string-descriptor.js";
+import { StringProxy } from "./string-proxy.js";
+
+const regExpParameterDescriptor: ParameterDescriptor = {
+    name: "regExp",
+    type: Type.String,
+    isMatrix: false,
+    isRequired: true
+};
+
+const errorMessageParameterDescriptor: ParameterDescriptor = {
+    name: "errorMessage",
+    type: Type.String,
+    isMatrix: false,
+    isRequired: false
+};
+
+@ProxyClass({
+    methodInfix: "RegExp"
+})
+export class RegExpProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends StringProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    @ProxyMethod({
+        type: Type.String,
+        isMatrix: true
+    })
+    validate(
+        @ProxyParameter(regExpParameterDescriptor) regExp: string,
+        @ProxyParameter(validateSParameterDescriptor) matrixSs: Matrix<string>,
+        @ProxyParameter(errorMessageParameterDescriptor) errorMessage: Nullishable<string>
+    ): MatrixResultError<string, ThrowError, TError> {
+        return this.validateString(new class extends RegExpValidator {
+            protected override createErrorMessage(s: string): string {
+                return errorMessage ?? super.createErrorMessage(s);
+            }
+        }(new RegExp(regExp)), matrixSs);
+    }
+
+    @ProxyMethod({
+        type: Type.Boolean,
+        isMatrix: true
+    })
+    isValid(
+        @ProxyParameter(regExpParameterDescriptor) regExp: string,
+        @ProxyParameter(validateSParameterDescriptor) matrixSs: Matrix<string>
+    ): MatrixResultError<boolean, ThrowError, TError> {
+        return this.isValidString(this.validate(regExp, matrixSs, undefined));
+    }
+}

package/src/utility/string-descriptor.ts

@@ -0,0 +1,13 @@
+import { type ParameterDescriptor, Type } from "../descriptor.js";
+
+export const sParameterDescriptor: ParameterDescriptor = {
+    name: "s",
+    type: Type.String,
+    isMatrix: true,
+    isRequired: true
+};
+
+export const validateSParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: sParameterDescriptor,
+    name: "validateS"
+};

package/src/utility/string-proxy.ts

@@ -0,0 +1,15 @@
+import type { StringValidation, StringValidator } from "@aidc-toolkit/utility";
+import { LibProxy } from "../lib-proxy.js";
+import type { ErrorExtends, Matrix, MatrixResultError } from "../types.js";
+
+export abstract class StringProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    protected validateString<TStringValidation extends StringValidation>(validator: StringValidator<TStringValidation>, matrixSs: Matrix<string>, validation?: TStringValidation): Matrix<string> {
+        return LibProxy.mapMatrixRangeError(matrixSs, (s) => {
+            validator.validate(s, validation);
+        });
+    }
+
+    protected isValidString(matrixValidateResults: MatrixResultError<string, ThrowError, TError>): MatrixResultError<boolean, ThrowError, TError> {
+        return this.mapMatrix(matrixValidateResults, validateResult => validateResult === "");
+    }
+}

package/src/utility/transformer-descriptor.ts

@@ -0,0 +1,27 @@
+import { type ParameterDescriptor, Type } from "../descriptor.js";
+
+export const valueParameterDescriptor: ParameterDescriptor = {
+    name: "value",
+    type: Type.Number,
+    isMatrix: true,
+    isRequired: true
+};
+
+export const startValueParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: valueParameterDescriptor,
+    name: "startValue",
+    isMatrix: false
+};
+
+export const countParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: valueParameterDescriptor,
+    name: "count",
+    isMatrix: false
+};
+
+export const tweakParameterDescriptor: ParameterDescriptor = {
+    name: "tweak",
+    type: Type.Number,
+    isMatrix: false,
+    isRequired: false
+};

package/src/utility/transformer-proxy.ts

@@ -0,0 +1,72 @@
+import { Sequence, Transformer, mapIterable } from "@aidc-toolkit/utility";
+import { type ParameterDescriptor, ProxyClass, ProxyMethod, ProxyParameter, Type } from "../descriptor.js";
+import { LibProxy } from "../lib-proxy.js";
+import type { ErrorExtends, Matrix, MatrixResultError, Nullishable, ResultError } from "../types.js";
+import {
+    countParameterDescriptor,
+    startValueParameterDescriptor,
+    tweakParameterDescriptor,
+    valueParameterDescriptor
+} from "./transformer-descriptor.js";
+
+const domainParameterDescriptor: ParameterDescriptor = {
+    name: "domain",
+    type: Type.Number,
+    isMatrix: false,
+    isRequired: true
+};
+
+// eslint-disable-next-line no-useless-assignment -- ESLint bug.
+const transformedValueParameterDescriptor: ParameterDescriptor = {
+    extendsDescriptor: valueParameterDescriptor,
+    name: "transformedValue"
+};
+
+@ProxyClass({
+    methodInfix: "Transform"
+})
+export class TransformerProxy<ThrowError extends boolean, TError extends ErrorExtends<ThrowError>, TInvocationContext, TBigInt> extends LibProxy<ThrowError, TError, TInvocationContext, TBigInt> {
+    @ProxyMethod({
+        type: Type.Number,
+        isMatrix: true
+    })
+    forward(
+        @ProxyParameter(domainParameterDescriptor) domain: number | bigint,
+        @ProxyParameter(valueParameterDescriptor) matrixValues: Matrix<number | bigint>,
+        @ProxyParameter(tweakParameterDescriptor) tweak: Nullishable<number | bigint>
+    ): MatrixResultError<ResultError<TBigInt, ThrowError, TError>, ThrowError, TError> {
+        const transformer = Transformer.get(domain, tweak ?? undefined);
+
+        return this.mapMatrix(matrixValues, value => this.mapBigInt(transformer.forward(value)));
+    }
+
+    @ProxyMethod({
+        infixBefore: "Sequence",
+        type: Type.Number,
+        isMatrix: true
+    })
+    forwardSequence(
+        @ProxyParameter(domainParameterDescriptor) domain: number | bigint,
+        @ProxyParameter(startValueParameterDescriptor) startValue: number,
+        @ProxyParameter(countParameterDescriptor) count: number,
+        @ProxyParameter(tweakParameterDescriptor) tweak: Nullishable<number | bigint>
+    ): Matrix<ResultError<TBigInt, ThrowError, TError>> {
+        this.appExtension.validateSequenceCount(count);
+
+        return LibProxy.matrixResult(mapIterable(Transformer.get(domain, tweak ?? undefined).forward(new Sequence(startValue, count)), value => this.mapBigInt(value)));
+    }
+
+    @ProxyMethod({
+        type: Type.Number,
+        isMatrix: true
+    })
+    reverse(
+        @ProxyParameter(domainParameterDescriptor) domain: number | bigint,
+        @ProxyParameter(transformedValueParameterDescriptor) matrixTransformedValues: Matrix<number | bigint>,
+        @ProxyParameter(tweakParameterDescriptor) tweak: Nullishable<number | bigint>
+    ): MatrixResultError<ResultError<TBigInt, ThrowError, TError>, ThrowError, TError> {
+        const transformer = Transformer.get(domain, tweak ?? undefined);
+
+        return this.mapMatrix(matrixTransformedValues, transformedValue => this.mapBigInt(transformer.reverse(transformedValue)));
+    }
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@aidc-toolkit/dev/tsconfig.json",
+  "compilerOptions": {
+    "experimentalDecorators": true
+  }
+}