@opra/common 1.5.0 → 1.5.2

package/types/document/api-document.d.ts

@@ -15,7 +15,6 @@ import { RpcApi } from './rpc/rpc-api.js';
 export declare class ApiDocument extends DocumentElement {
     protected [kTypeNSMap]: WeakMap<DataType, string>;
     readonly id: string;
-    scopes?: string[];
     url?: string;
     info: OpraSchema.DocumentInfo;
     references: ResponsiveMap<ApiDocument>;
@@ -36,10 +35,10 @@ export declare class ApiDocument extends DocumentElement {
      */
     export(options?: ApiDocument.ExportOptions): OpraSchema.ApiDocument;
     invalidate(): void;
-    protected _findDataType(nameOrCtor: string | Type | Function | EnumType.EnumArray | EnumType.EnumObject, scope?: string | string[], visitedRefs?: WeakMap<ApiDocument, boolean>): DataType | undefined;
+    protected _findDataType(nameOrCtor: string | Type | Function | EnumType.EnumArray | EnumType.EnumObject, scope?: string, visitedRefs?: WeakMap<ApiDocument, boolean>): DataType | undefined;
 }
 export declare namespace ApiDocument {
     interface ExportOptions {
-        scopes?: string[];
+        scope?: string;
     }
 }

package/types/document/common/document-init-context.d.ts

@@ -10,7 +10,6 @@ export declare class DocumentInitContext {
     error: OpraDocumentError;
     maxErrors: number;
     showErrorDetails: boolean;
-    scopes?: string[];
     constructor(options?: DocumentInitContext.Options);
     addError(error: Error | OpraDocumentError.ErrorDetail | string): void;
     enter(path: string, fn: () => any): any;

package/types/document/common/document-node.d.ts

@@ -19,41 +19,41 @@ export declare class DocumentNode {
     readonly element: DocumentElement;
     constructor(element: DocumentElement, parent?: DocumentNode);
     getDocument(): ApiDocument;
-    hasDataType(nameOrCtor: string | Type | Function | object | any[], scope?: string | string[]): boolean;
-    findDataType(nameOrCtor: string | Type | Function | object | any[], scope?: string | string[]): DataType | undefined;
+    hasDataType(nameOrCtor: string | Type | Function | object | any[], scope?: string): boolean;
+    findDataType(nameOrCtor: string | Type | Function | object | any[], scope?: string): DataType | undefined;
     /**
      * Returns DataType instance by name or Constructor. Returns undefined if not found
      */
-    getDataType(nameOrCtor: string | Type | Function | object | any[], scope?: string | string[]): DataType;
+    getDataType(nameOrCtor: string | Type | Function | object | any[], scope?: string): DataType;
     getDataTypeNameWithNs(dataType: DataType): string | undefined;
     /**
      * Returns ComplexType instance by name or Constructor.
      * Returns undefined if not found
      * Throws error if data type is not a ComplexType
      */
-    getComplexType(nameOrCtor: string | Type | Function, scope?: string | string[]): ComplexType;
+    getComplexType(nameOrCtor: string | Type | Function, scope?: string): ComplexType;
     /**
      * Returns SimpleType instance by name or Constructor.
      * Returns undefined if not found
      * Throws error if data type is not a SimpleType
      */
-    getSimpleType(nameOrCtor: string | Type, scope?: string | string[]): SimpleType;
+    getSimpleType(nameOrCtor: string | Type, scope?: string): SimpleType;
     /**
      * Returns EnumType instance by name or Constructor.
      * Returns undefined if not found
      * Throws error if data type is not a EnumType
      */
-    getEnumType(nameOrCtor: string | object | any[], scope?: string | string[]): EnumType;
+    getEnumType(nameOrCtor: string | object | any[], scope?: string): EnumType;
     /**
      * Returns EnumType instance by name or Constructor.
      * Returns undefined if not found
      * Throws error if data type is not a MappedType
      */
-    getMappedType(nameOrCtor: string | object | any[], scope?: string | string[]): MappedType;
+    getMappedType(nameOrCtor: string | object | any[], scope?: string): MappedType;
     /**
      * Returns EnumType instance by name or Constructor.
      * Returns undefined if not found
      * Throws error if data type is not a MixinType
      */
-    getMixinType(nameOrCtor: string | object | any[], scope?: string | string[]): MixinType;
+    getMixinType(nameOrCtor: string | object | any[], scope?: string): MixinType;
 }

package/types/document/data-type/api-field.d.ts

@@ -1,58 +1,43 @@
-import type { Combine, TypeThunkAsync } from 'ts-gems';
+import type { Combine, StrictOmit, TypeThunkAsync } from 'ts-gems';
 import { OpraSchema } from '../../schema/index.js';
 import type { ApiDocument } from '../api-document.js';
 import { DocumentElement } from '../common/document-element.js';
-import { ApiFieldDecorator } from '../decorators/api-field-decorator.js';
+import { ApiFieldDecoratorFactory } from '../decorators/api-field-decorator.js';
 import type { ComplexType } from './complex-type.js';
 import type { DataType } from './data-type.js';
 import type { EnumType } from './enum-type.js';
 import type { MappedType } from './mapped-type.js';
 import type { MixinType } from './mixin-type.js';
-/**
- * @namespace ApiField
- */
-export declare namespace ApiField {
-    interface Metadata extends Combine<{
-        type?: string | OpraSchema.DataType | TypeThunkAsync | EnumType.EnumObject | EnumType.EnumArray | object;
-    }, OpraSchema.Field> {
-    }
-    interface Options extends Partial<Metadata> {
-        scopes?: (string | RegExp)[];
-    }
-    interface InitArguments extends Combine<{
-        name: string;
-        origin?: ComplexType | MappedType | MixinType;
-        type?: DataType;
-    }, Metadata> {
-        scopes?: (string | RegExp)[];
-    }
-}
 /**
  * Type definition of ComplexType constructor type
  * @type ApiFieldConstructor
  */
-export interface ApiFieldConstructor extends ApiFieldDecorator {
+export interface ApiFieldConstructor extends ApiFieldDecoratorFactory {
     prototype: ApiField;
     new (owner: ComplexType | MappedType | MixinType, args: ApiField.InitArguments): ApiField;
 }
 /**
+ * The ApiField represents a descriptive metadata structure for API fields,
+ * supporting features like data type definition, scoping, localization, and constraints.
+ * This class extends DocumentElement, inheriting base document structure capabilities.
+ *
  * @class ApiField
  */
 export interface ApiField extends ApiFieldClass {
 }
 /**
- * @constructor ApiField
  * @decorator ApiField
  */
 export declare const ApiField: ApiFieldConstructor;
 /**
- *
- * @class ApiField
+ * The ApiFieldClass represents a descriptive metadata structure for API fields,
+ * supporting features like data type definition, scoping, localization, and constraints.
+ * This class extends DocumentElement, inheriting base document structure capabilities.
  */
 declare class ApiFieldClass extends DocumentElement {
     readonly owner: ComplexType | MappedType | MixinType;
     readonly origin?: ComplexType | MappedType | MixinType;
-    readonly scopes?: (string | RegExp)[];
+    readonly scopePattern?: (string | RegExp)[];
     readonly name: string;
     readonly type: DataType;
     readonly description?: string;
@@ -67,7 +52,35 @@ declare class ApiFieldClass extends DocumentElement {
     readonly readonly?: boolean;
     readonly writeonly?: boolean;
     readonly examples?: any[] | Record<string, any>;
-    inScope(scopes?: string | string[]): boolean;
+    inScope(scope: string): boolean;
     toJSON(options?: ApiDocument.ExportOptions): OpraSchema.Field;
 }
+/**
+ * @namespace ApiField
+ */
+export declare namespace ApiField {
+    interface Metadata extends Combine<{
+        type?: string | OpraSchema.DataType | TypeThunkAsync | EnumType.EnumObject | EnumType.EnumArray | object;
+    }, OpraSchema.Field> {
+        scopePattern?: (string | RegExp)[];
+        overrides?: StrictOmit<Metadata, 'overrides' | 'type' | 'isArray'>[];
+    }
+    interface Options extends Partial<StrictOmit<Metadata, 'overrides' | 'scopePattern'>> {
+        /**
+         * A variable that defines the pattern or patterns used to determine scope.
+         * This can either be a single string or regular expression, or an array containing multiple strings or regular expressions.
+         *
+         * - If a single string or RegExp is provided, it is directly used as the scope pattern.
+         * - If an array is provided, each element within the array is used as a valid scope pattern.
+         */
+        scopePattern?: (string | RegExp) | (string | RegExp)[];
+    }
+    interface InitArguments extends Combine<{
+        name: string;
+        origin?: ComplexType | MappedType | MixinType;
+        type?: DataType;
+    }, Metadata> {
+        scopePattern?: (string | RegExp)[];
+    }
+}
 export {};

package/types/document/data-type/complex-type-base.d.ts

@@ -46,22 +46,24 @@ declare abstract class ComplexTypeBaseClass extends DataType {
     /**
      *
      */
-    findField(nameOrPath: string): ApiField | undefined;
+    findField(nameOrPath: string, scope?: string): ApiField | undefined;
     /**
      *
      */
-    getField(nameOrPath: string): ApiField;
+    getField(nameOrPath: string, scope?: string): ApiField;
     /**
      *
      */
     parseFieldPath(fieldPath: string, options?: {
         allowSigns?: 'first' | 'each';
+        scope?: string;
     }): ComplexType.ParsedFieldPath[];
     /**
      *
      */
     normalizeFieldPath(fieldPath: string, options?: {
         allowSigns?: 'first' | 'each';
+        scope?: string;
     }): string;
     /**
      *

package/types/document/data-type/complex-type.d.ts

@@ -74,5 +74,6 @@ declare abstract class ComplexTypeClass extends ComplexTypeBase {
     readonly ctor?: Type;
     extendsFrom(baseType: DataType | string | Type | object): boolean;
     toJSON(options?: ApiDocument.ExportOptions): OpraSchema.ComplexType;
+    protected _locateBase(callback: (base: ComplexTypeBase) => boolean): ComplexTypeBase | undefined;
 }
 export {};

package/types/document/data-type/data-type.d.ts

@@ -16,14 +16,14 @@ export declare namespace DataType {
     }
     interface Options extends Partial<StrictOmit<Metadata, 'kind' | 'examples'>> {
         embedded?: boolean;
-        scopes?: (string | RegExp)[];
+        scopePattern?: (string | RegExp) | (string | RegExp)[];
     }
     interface InitArguments extends DataType.Metadata {
-        scopes?: (string | RegExp)[];
+        scopePattern?: (string | RegExp)[];
     }
     interface GenerateCodecOptions extends ValidationOptions {
         documentElement?: DocumentElement;
-        scope?: string | string[];
+        scope?: string;
         caseInSensitive?: boolean;
         partial?: boolean | 'deep';
         projection?: string[] | FieldsProjection | '*';
@@ -53,7 +53,7 @@ export declare const DataType: DataTypeStatic;
 declare abstract class DataTypeClass extends DocumentElement {
     readonly kind: OpraSchema.DataType.Kind;
     readonly owner: DocumentElement;
-    readonly scopes?: (string | RegExp)[];
+    readonly scopePattern?: (string | RegExp)[];
     readonly name?: string;
     readonly description?: string;
     readonly abstract?: boolean;
@@ -61,9 +61,10 @@ declare abstract class DataTypeClass extends DocumentElement {
     abstract generateCodec(codec: 'encode' | 'decode', options?: DataType.GenerateCodecOptions): Validator;
     get embedded(): any;
     abstract extendsFrom(baseType: DataType | string | Type | object): boolean;
-    inScope(scopes?: string | string[]): boolean;
+    inScope(scope: string): boolean;
     toJSON(options?: ApiDocument.ExportOptions): OpraSchema.DataType;
     toString(): string;
+    protected abstract _locateBase(callback: (base: DataType) => boolean): DataType | undefined;
     [nodeInspectCustom](): string;
 }
 export {};

package/types/document/data-type/enum-type.d.ts

@@ -67,5 +67,6 @@ declare class EnumTypeClass extends DataType {
     extendsFrom(baseType: DataType | string | Type | object): boolean;
     generateCodec(): Validator;
     toJSON(options?: ApiDocument.ExportOptions): OpraSchema.EnumType;
+    protected _locateBase(callback: (base: EnumType) => boolean): EnumType | undefined;
 }
 export {};

package/types/document/data-type/extended-types/field-path.type.d.ts

@@ -7,8 +7,8 @@ export declare class FieldPathType {
     constructor(attributes?: Partial<FieldPathType>);
     dataType?: Type | string;
     allowSigns?: 'first' | 'each';
-    [DECODER](properties: Partial<this>, element: DocumentElement): Validator;
-    [ENCODER](properties: Partial<this>, element: DocumentElement): Validator;
+    [DECODER](properties: Partial<this>, element: DocumentElement, scope?: string): Validator;
+    [ENCODER](properties: Partial<this>, element: DocumentElement, scope?: string): Validator;
     toJSON(properties: Partial<FieldPathType>, element: DocumentElement, options?: ApiDocument.ExportOptions): {
         dataType: string | import("../../../schema/opra-schema.js").ComplexType;
         allowSigns: "first" | "each" | undefined;

package/types/document/data-type/mapped-type.d.ts

@@ -70,5 +70,6 @@ declare class MappedTypeClass extends ComplexTypeBase {
     readonly required?: Field.Name[] | boolean;
     extendsFrom(baseType: DataType | string | Type | object): boolean;
     toJSON(options?: ApiDocument.ExportOptions): OpraSchema.MappedType;
+    protected _locateBase(callback: (base: ComplexTypeBase) => boolean): ComplexTypeBase | undefined;
 }
 export {};

package/types/document/data-type/mixin-type.d.ts

@@ -79,5 +79,6 @@ declare class MixinTypeClass extends ComplexTypeBase {
     readonly types: (ComplexType | MixinType | MappedType)[];
     extendsFrom(baseType: DataType | string | Type | object): boolean;
     toJSON(options?: ApiDocument.ExportOptions): OpraSchema.MixinType;
+    protected _locateBase(callback: (base: ComplexTypeBase) => boolean): ComplexTypeBase | undefined;
 }
 export {};

package/types/document/data-type/simple-type.d.ts

@@ -28,7 +28,7 @@ export declare namespace SimpleType {
     }
     interface Attribute extends OpraSchema.Attribute {
     }
-    type ValidatorGenerator = (properties: Record<string, any>, element: DocumentElement) => Validator;
+    type ValidatorGenerator = (properties: Record<string, any>, element: DocumentElement, scope?: string) => Validator;
 }
 /**
  * Type definition for MixinType

package/types/document/decorators/api-field-decorator.d.ts

@@ -1,5 +1,7 @@
 import type { ApiField } from '../data-type/api-field.js';
-export interface ApiFieldDecorator {
-    (options?: ApiField.Options): PropertyDecorator;
+export interface ApiFieldDecorator extends PropertyDecorator {
 }
-export declare function ApiFieldDecorator(options?: ApiField.Options): PropertyDecorator;
+export interface ApiFieldDecoratorFactory {
+    (options?: ApiField.Options): ApiFieldDecorator;
+}
+export declare function ApiFieldDecoratorFactory(options?: ApiField.Options): ApiFieldDecorator;

package/types/document/decorators/simple-type.decorator.d.ts

@@ -1,6 +1,40 @@
 import { OpraSchema } from '../../schema/index.js';
 import type { SimpleType } from '../data-type/simple-type';
 export interface SimpleTypeDecorator extends ClassDecorator {
+    /**
+     * This function is used to attach one or more usage examples to a `SimpleType` model.
+     * These examples serve as additional descriptive metadata, often useful for documentation
+     * or validation purposes. They can help define how a specific value should be used,
+     * making it easier to understand or test the defined `SimpleType` model.
+     *
+     * @param value - The usage example to associate with the `SimpleType` model.
+     *                It can be of any type and is intended to represent a realistic
+     *                value that fits the model's constraints.
+     *                For instance, if the `SimpleType` model represents a string with
+     *                specific formatting, this parameter provides an example of a compliant string.
+     *
+     * @param description (optional) - A brief description explaining the purpose or
+     *                                 context of the example provided in the `value` parameter.
+     *                                 This description can provide additional context or
+     *                                 clarify why the example is relevant.
+     *                                 For instance, for a `SimpleType` representing email strings,
+     *                                 the description could be: "An example of a valid email address".
+     *
+     * @example
+     * ```typescript
+     * class MyModel {
+     *   @Example("example@example.com", "A valid email address example")
+     *   email!: string;
+     *
+     *   @Example(42, "An example of an integer age value")
+     *   age!: number;
+     * }
+     * ```
+     *
+     * In the above example:
+     * - The `email` property is associated with a usage example of "example@example.com".
+     * - The `age` property includes an example of 42.
+     */
     Example(value: any, description?: string): SimpleTypeDecorator;
 }
 export interface SimpleTypeDecoratorFactory {

package/types/document/factory/api-document.factory.d.ts

@@ -10,7 +10,6 @@ export declare namespace ApiDocumentFactory {
         references?: Record<string, ReferenceThunk>;
         types?: DataTypeInitSources;
         api?: StrictOmit<HttpApiFactory.InitArguments, 'owner'> | StrictOmit<RpcApiFactory.InitArguments, 'owner'>;
-        scopes?: string | string[];
     }
     type ReferenceSource = string | OpraSchema.ApiDocument | InitArguments | ApiDocument;
     type ReferenceThunk = ThunkAsync<ReferenceSource>;
@@ -24,7 +23,7 @@ export declare class ApiDocumentFactory {
     /**
      * Creates ApiDocument instance from given schema object
      */
-    static createDocument(schemaOrUrl: string | PartialSome<OpraSchema.ApiDocument, 'spec'> | ApiDocumentFactory.InitArguments, options?: Partial<Pick<DocumentInitContext, 'maxErrors' | 'showErrorDetails' | 'scopes'>> | DocumentInitContext): Promise<ApiDocument>;
+    static createDocument(schemaOrUrl: string | PartialSome<OpraSchema.ApiDocument, 'spec'> | ApiDocumentFactory.InitArguments, options?: Partial<Pick<DocumentInitContext, 'maxErrors' | 'showErrorDetails'>> | DocumentInitContext): Promise<ApiDocument>;
     /**
      * Downloads schema from the given URL and creates the document instance   * @param url
      */

package/types/document/http/http-api.d.ts

@@ -24,5 +24,5 @@ export declare class HttpApi extends ApiBase {
     findController(resourcePath: string): HttpController | undefined;
     findOperation(controller: Type, operationName: string): HttpOperation | undefined;
     findOperation(resourcePath: string, operationName: string): HttpOperation | undefined;
-    toJSON(options: ApiDocument.ExportOptions): OpraSchema.HttpApi;
+    toJSON(options?: ApiDocument.ExportOptions): OpraSchema.HttpApi;
 }

package/types/document/utils/test-scope-match.d.ts

@@ -0,0 +1 @@
+export declare function testScopeMatch(scope: string, pattern?: (string | RegExp) | (string | RegExp)[]): boolean;

package/types/filter/filter-rules.d.ts

@@ -1,7 +1,7 @@
 import '../polifils/array-find-last.js';
 import type { StrictOmit } from 'ts-gems';
 import { Validator } from 'valgen';
-import type { ComplexType, DocumentElement } from '../document/index.js';
+import type { ComplexType } from '../document/index.js';
 import { ResponsiveMap } from '../helpers/index.js';
 import { OpraSchema } from '../schema/index.js';
 import { type ComparisonOperator, Expression } from './ast/index.js';
@@ -21,8 +21,8 @@ export declare class FilterRules {
     set(fieldName: string, options?: Partial<StrictOmit<FilterRules.Rule, 'operators'>> & {
         operators?: ComparisonOperator[] | string;
     }): void;
-    normalizeFilter(filter: OpraSchema.Field.QualifiedName | Expression, currentType?: ComplexType, element?: DocumentElement): Expression | undefined;
-    protected normalizeFilterAst(ast: Expression, stack: Expression[], currentType?: ComplexType, scopes?: string[]): Expression | undefined;
+    normalizeFilter(filter: OpraSchema.Field.QualifiedName | Expression, currentType?: ComplexType, scope?: any): Expression | undefined;
+    protected normalizeFilterAst(ast: Expression, stack: Expression[], currentType?: ComplexType, scope?: string): Expression | undefined;
     toJSON(): Record<string, FilterRules.Rule>;
     [Symbol.iterator](): IterableIterator<[string, FilterRules.Rule]>;
 }