@opra/common 0.13.0 → 0.15.0

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

@@ -0,0 +1,102 @@
+import { Type } from 'ts-gems';
+import { ResponsiveMap } from '../helpers/index.js';
+import { OpraSchema } from '../schema/index.js';
+import { ComplexType } from './data-type/complex-type.js';
+import type { DataType } from './data-type/data-type.js';
+import { SimpleType } from './data-type/simple-type.js';
+import type { Collection } from './resource/collection.js';
+import { Resource } from './resource/resource.js';
+import { Singleton } from './resource/singleton.js';
+export declare class ApiDocument {
+    protected _typeCache: ResponsiveMap<DataType | null>;
+    protected _typesCacheByCtor: Map<object | Type<any>, DataType | null>;
+    url?: string;
+    info: OpraSchema.DocumentInfo;
+    references: ResponsiveMap<ApiDocument>;
+    types: ResponsiveMap<DataType>;
+    resources: ResponsiveMap<Resource>;
+    constructor();
+    /**
+     * Returns DataType instance by name or Constructor. Returns undefined if not found
+     * @param nameOrCtor
+     * @param silent
+     */
+    getDataType(nameOrCtor: string | Type | object, silent: true): DataType | undefined;
+    /**
+     * Returns DataType instance by name or Constructor. Throws error  if not found
+     * @param nameOrCtor
+     */
+    getDataType(nameOrCtor: string | Type | object): DataType;
+    /**
+     * Returns ComplexType instance by name or Constructor.
+     * Returns undefined if not found
+     * Throws error if data type is not a ComplexType
+     * @param nameOrCtor
+     * @param silent
+     */
+    getComplexType(nameOrCtor: string | Type, silent: true): ComplexType | undefined;
+    /**
+     * Returns ComplexType instance by name or Constructor.
+     * Throws error undefined if not found or data type is not a ComplexType
+     * @param nameOrCtor
+     */
+    getComplexType(nameOrCtor: string | Type): ComplexType;
+    /**
+     * Returns SimpleType instance by name or Constructor.
+     * Returns undefined if not found
+     * Throws error if data type is not a SimpleType
+     * @param nameOrCtor
+     * @param silent
+     */
+    getSimpleType(nameOrCtor: string | Type, silent: true): SimpleType | undefined;
+    /**
+     Returns SimpleType instance by name or Constructor.
+     Throws error undefined if not found or data type is not a SimpleType
+     * @param nameOrCtor
+     */
+    getSimpleType(nameOrCtor: string | Type): SimpleType;
+    /**
+     * Returns Resource instance by path. Returns undefined if not found
+     * @param path
+     * @param silent
+     */
+    getResource(path: string, silent: boolean): Resource | undefined;
+    /**
+     * Returns Resource instance by path. Throws error if not found
+     * @param path
+     */
+    getResource(path: string): Resource;
+    /**
+     * Returns Collection resource instance by path
+     * Returns undefined if not found
+     * Throws error if resource is not a Collection
+     * @param path
+     * @param silent
+     */
+    getCollection(path: string, silent: true): Collection | undefined;
+    /**
+     * Returns ComplexType instance by name or Constructor.
+     * Throws error undefined if not found or data type is not a ComplexType
+     * @param path
+     */
+    getCollection(path: string): Collection;
+    /**
+     * Returns Singleton resource instance by path
+     * Returns undefined if not found
+     * Throws error if resource is not a Collection
+     * @param path
+     * @param silent
+     */
+    getSingleton(path: string, silent: true): Singleton | undefined;
+    /**
+     * Returns ComplexType instance by name or Constructor.
+     * Throws error undefined if not found or data type is not a ComplexType
+     * @param path
+     */
+    getSingleton(path: string): Singleton;
+    /**
+     * Export as Opra schema definition object
+     */
+    exportSchema(): OpraSchema.ApiDocument;
+    invalidate(): void;
+}

package/esm/document/api-document.js

@@ -0,0 +1,207 @@
+import { NotAcceptableError, NotFoundError } from '../exception/index.js';
+import { cloneObject, omitUndefined, ResponsiveMap } from '../helpers/index.js';
+import { OpraSchema } from '../schema/index.js';
+import { NAMESPACE_PATTERN } from './constants.js';
+import { ComplexType } from './data-type/complex-type.js';
+import { SimpleType } from './data-type/simple-type.js';
+export class ApiDocument {
+    constructor() {
+        this._typeCache = new ResponsiveMap();
+        this._typesCacheByCtor = new Map();
+        this.references = new ResponsiveMap();
+        this.types = new ResponsiveMap();
+        this.resources = new ResponsiveMap();
+        this.info = {
+            version: '',
+            title: ''
+        };
+    }
+    getDataType(nameOrCtor, silent) {
+        let dataType;
+        if (nameOrCtor === Object)
+            nameOrCtor = 'any';
+        const nameOrCtorName = typeof nameOrCtor === 'function' ? nameOrCtor.name : nameOrCtor;
+        // Try to get instance from cache
+        const t = typeof nameOrCtor === 'string'
+            ? this._typeCache.get(nameOrCtor)
+            : this._typesCacheByCtor.get(nameOrCtor);
+        if (t)
+            return t;
+        if (t === null) {
+            if (silent)
+                return;
+            throw new NotFoundError(`Data type "${nameOrCtorName}" does not exists`);
+        }
+        if (typeof nameOrCtor === 'string') {
+            const m = NAMESPACE_PATTERN.exec(nameOrCtor);
+            if (!m)
+                throw new NotFoundError(`Invalid data type name "${nameOrCtorName}"`);
+            // If given string has namespace pattern (ns:type_name)
+            if (m[2]) {
+                const ref = this.references.get(m[1]);
+                if (!ref) {
+                    if (silent)
+                        return;
+                    throw new NotFoundError(`Reference "${m[1]}" not found`);
+                }
+                dataType = ref.getDataType(m[2]);
+                this._typeCache.set(nameOrCtor, dataType);
+            }
+            else {
+                const name = m[1];
+                // Get instance from own types
+                dataType = this.types.get(name);
+                // if not found, search in references (from last to first)
+                if (!dataType) {
+                    const references = Array.from(this.references.values()).reverse();
+                    for (const ref of references) {
+                        dataType = ref.getDataType(name);
+                        if (dataType)
+                            break;
+                    }
+                }
+                if (dataType)
+                    this._typeCache.set(dataType.name || name, dataType);
+            }
+        }
+        else if (typeof nameOrCtor === 'function') {
+            const types = Array.from(this.types.values()).reverse();
+            for (const dt of types) {
+                if ((dt instanceof ComplexType || dt instanceof SimpleType) && dt.own.ctor === nameOrCtor) {
+                    dataType = dt;
+                    break;
+                }
+            }
+            // if not found, search in references (from last to first)
+            if (!dataType) {
+                const references = Array.from(this.references.values()).reverse();
+                for (const ref of references) {
+                    dataType = ref.getDataType(nameOrCtor, true);
+                    if (dataType)
+                        break;
+                }
+            }
+        }
+        if (dataType) {
+            if ((dataType instanceof ComplexType || dataType instanceof SimpleType) &&
+                dataType.own?.ctor && dataType.own.ctor !== Object)
+                this._typesCacheByCtor.set(dataType.own.ctor, dataType);
+            return dataType;
+        }
+        else {
+            if (typeof nameOrCtor === 'string')
+                this._typeCache.set(nameOrCtor, null);
+            else
+                this._typesCacheByCtor.set(nameOrCtor, null);
+        }
+        if (silent)
+            return;
+        throw new NotFoundError(`Data type "${nameOrCtorName}" does not exists`);
+    }
+    getComplexType(nameOrCtor, silent) {
+        if (nameOrCtor === Object)
+            nameOrCtor = 'object';
+        const t = this.getDataType(nameOrCtor);
+        if (!t && silent)
+            return;
+        if (t && t.kind === OpraSchema.ComplexType.Kind)
+            return t;
+        throw new NotAcceptableError(`Data type "${t.name}" is not a ComplexType`);
+    }
+    getSimpleType(nameOrCtor, silent) {
+        const t = this.getDataType(nameOrCtor);
+        if (!t && silent)
+            return;
+        if (t && t.kind === OpraSchema.SimpleType.Kind)
+            return t;
+        throw new NotAcceptableError(`Data type "${t.name || t}" is not a SimpleType`);
+    }
+    getResource(path, silent) {
+        let resource;
+        const m = NAMESPACE_PATTERN.exec(path);
+        if (!m)
+            throw new NotFoundError(`Invalid resource path "${path}"`);
+        // If given string has namespace pattern (ns:type_name)
+        if (m[2]) {
+            const ref = this.references.get(m[1]);
+            if (!ref) {
+                if (silent)
+                    return;
+                throw new NotFoundError(`Reference "${m[1]}" not found`);
+            }
+            return ref.getResource(m[2]);
+        }
+        else {
+            const name = m[1];
+            // Get instance from own types
+            resource = this.resources.get(name);
+            if (resource)
+                return resource;
+            // if not found, search in references (from last to first)
+            const references = Array.from(this.references.values()).reverse();
+            for (const ref of references) {
+                resource = silent ? ref.getResource(name, silent) : ref.getResource(name);
+                if (resource)
+                    return resource;
+            }
+        }
+        if (silent)
+            return;
+        throw new NotFoundError(`Resource not found (${path})`);
+    }
+    getCollection(path, silent) {
+        const t = this.getResource(path);
+        if (!t && silent)
+            return;
+        if (t && t.kind === OpraSchema.Collection.Kind)
+            return t;
+        throw new NotAcceptableError(`Resource type "${t.name}" is not a Collection`);
+    }
+    getSingleton(path, silent) {
+        const t = this.getResource(path);
+        if (!t && silent)
+            return;
+        if (t && t.kind === OpraSchema.Singleton.Kind)
+            return t;
+        throw new NotAcceptableError(`Resource type "${t.name}" is not a Singleton`);
+    }
+    /**
+     * Export as Opra schema definition object
+     */
+    exportSchema() {
+        const schema = {
+            version: OpraSchema.SpecVersion,
+            url: this.url,
+            info: cloneObject(this.info)
+        };
+        if (this.references.size) {
+            const references = {};
+            let i = 0;
+            for (const [ns, r] of this.references.entries()) {
+                if (ns.toLowerCase() === 'opra')
+                    continue;
+                references[ns] = r.url ? r.url : r.exportSchema();
+                i++;
+            }
+            if (i)
+                schema.references = references;
+        }
+        if (this.resources.size) {
+            const resources = schema.resources = {};
+            for (const [name, r] of this.resources.entries()) {
+                resources[name] = r.exportSchema();
+            }
+        }
+        if (this.types.size) {
+            const types = schema.types = {};
+            for (const [name, r] of this.types.entries()) {
+                types[name] = r.exportSchema();
+            }
+        }
+        return omitUndefined(schema);
+    }
+    invalidate() {
+        this._typeCache.clear();
+        this._typesCacheByCtor.clear();
+    }
+}

package/esm/document/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const METADATA_KEY: unique symbol;
+export declare const NAMESPACE_PATTERN: RegExp;
+export declare const TYPENAME_PATTERN: RegExp;

package/esm/document/constants.js

@@ -0,0 +1,3 @@
+export const METADATA_KEY = Symbol.for('opra.metadata');
+export const NAMESPACE_PATTERN = /([A-Z$_]\w+)(?::.+)?/i;
+export const TYPENAME_PATTERN = /^(.*)Type$/;

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

@@ -0,0 +1,41 @@
+import { StrictOmit, Type } from 'ts-gems';
+import { OpraSchema } from '../../schema/index.js';
+import { TypeThunkAsync } from '../../types.js';
+import type { ComplexType } from './complex-type.js';
+import { DataType } from './data-type.js';
+export declare namespace ApiField {
+    interface InitArguments extends StrictOmit<OpraSchema.Field, 'type'> {
+        name: string;
+        type: DataType;
+        origin?: ComplexType;
+    }
+    interface DecoratorOptions extends Partial<StrictOmit<OpraSchema.Field, 'isArray' | 'type'>> {
+        type?: string | OpraSchema.DataType | TypeThunkAsync;
+        enum?: OpraSchema.EnumObject | string[];
+    }
+    interface Metadata extends StrictOmit<OpraSchema.Field, 'type'> {
+        type?: string | OpraSchema.DataType | TypeThunkAsync;
+        enum?: OpraSchema.EnumObject;
+        designType?: Type;
+    }
+}
+export interface ApiField extends StrictOmit<OpraSchema.Field, 'type'> {
+    readonly owner: ComplexType;
+    readonly origin?: ComplexType;
+    readonly type: DataType;
+    readonly name: string;
+    exportSchema(): OpraSchema.Field;
+}
+/**
+ * Type definition of ComplexType constructor type
+ * @type ApiFieldConstructor
+ */
+export interface ApiFieldConstructor {
+    new (owner: ComplexType, init: ApiField.InitArguments): ApiField;
+    (options?: ApiField.DecoratorOptions): PropertyDecorator;
+    prototype: ApiField;
+}
+/**
+ * @class ComplexType
+ */
+export declare const ApiField: ApiFieldConstructor;

package/esm/document/data-type/api-field.js

@@ -0,0 +1,79 @@
+import { omitUndefined } from '../../helpers/index.js';
+import { OpraSchema } from '../../schema/index.js';
+import { METADATA_KEY } from '../constants.js';
+import { EnumType } from './enum-type.js';
+/**
+ * @class ComplexType
+ */
+export const ApiField = function (...args) {
+    // ClassDecorator
+    if (!this) {
+        const [options] = args;
+        return function (target, propertyKey) {
+            if (typeof propertyKey !== 'string')
+                throw new TypeError(`Symbol properties can't be used as a field`);
+            const metadata = Reflect.getOwnMetadata(METADATA_KEY, target.constructor) || {};
+            metadata.kind = OpraSchema.ComplexType.Kind;
+            metadata.fields = metadata.fields || {};
+            const designType = Reflect.getMetadata('design:type', target, propertyKey);
+            const isArray = designType === Array;
+            const elemMeta = metadata.fields[propertyKey] = {
+                ...options,
+                enum: undefined,
+                designType: isArray ? undefined : designType
+            };
+            if (designType === Array)
+                elemMeta.isArray = true;
+            if (options?.enum) {
+                elemMeta.type = undefined;
+                if (Array.isArray(options.enum)) {
+                    const enumObj = options.enum.reduce((o, v) => {
+                        o[v] = v;
+                        return o;
+                    }, {});
+                    EnumType(enumObj);
+                    elemMeta.enum = enumObj;
+                }
+                else {
+                    const m = Reflect.getOwnMetadata(METADATA_KEY, options?.enum);
+                    if (!OpraSchema.isEnumType(m))
+                        throw new TypeError(`Invalid "enum" value. Did you forget to set metadata using EnumType() method?`);
+                    elemMeta.enum = options.enum;
+                }
+            }
+            Reflect.defineMetadata(METADATA_KEY, omitUndefined(metadata), target.constructor);
+        };
+    }
+    // Constructor
+    const [owner, init] = args;
+    const _this = this;
+    _this.owner = owner;
+    _this.name = init.name;
+    _this.origin = init.origin || owner;
+    _this.type = init.type;
+    if (init?.description)
+        this.description = init?.description;
+    if (init?.isArray != null)
+        this.isArray = init?.isArray;
+    this.default = init?.default;
+    this.fixed = init?.fixed;
+    if (init?.deprecated != null)
+        this.deprecated = init?.deprecated;
+    if (init?.exclusive != null)
+        this.exclusive = init?.exclusive;
+    if (init?.required != null)
+        this.required = init?.required;
+};
+const proto = {
+    exportSchema() {
+        const out = {
+            type: this.type.name ? this.type.name : this.type.exportSchema(),
+            description: this.description,
+            isArray: this.isArray,
+            default: this.default,
+            fixed: this.fixed
+        };
+        return out;
+    }
+};
+Object.assign(ApiField.prototype, proto);

package/esm/document/data-type/builtin/any.type.d.ts

@@ -0,0 +1,2 @@
+export declare class AnyType {
+}

package/esm/document/data-type/builtin/any.type.js

@@ -0,0 +1,11 @@
+import { __decorate } from "tslib";
+import { SimpleType } from '../simple-type.js';
+let AnyType = class AnyType {
+};
+AnyType = __decorate([
+    SimpleType({
+        description: 'Any value',
+        ctor: Object
+    })
+], AnyType);
+export { AnyType };

package/esm/document/data-type/builtin/base64.type.d.ts

@@ -0,0 +1,6 @@
+export declare class Base64Type {
+    decode(v: any): ArrayBuffer | undefined;
+    encode(v: any): string | undefined;
+    coerce(v: any): ArrayBuffer | undefined;
+    validate(v: any): void;
+}

package/esm/document/data-type/builtin/base64.type.js

@@ -0,0 +1,35 @@
+import { __decorate } from "tslib";
+import { SimpleType } from '../simple-type.js';
+const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:(?:[A-Za-z0-9+/][AQgw](:?==)?)|(?:[A-Za-z0-9+/]{2}[AEIMQUYcgkosw048]=?))?$/;
+let Base64Type = class Base64Type {
+    decode(v) {
+        if (v == null)
+            return v;
+        if (typeof v === 'string')
+            this.validate(v);
+        return Buffer.from(v, 'base64').buffer.slice(0);
+    }
+    encode(v) {
+        if (v == null)
+            return v;
+        if (Buffer.isBuffer(v))
+            return v.toString('base64');
+        return Buffer.from(v).toString('base64');
+    }
+    coerce(v) {
+        if (v instanceof ArrayBuffer)
+            return v;
+        return this.decode(v);
+    }
+    validate(v) {
+        if (!(typeof v === 'string' && BASE64_PATTERN.test(v)))
+            throw new TypeError(`Invalid base64 value "${String(v).substring(0, 10)}..."`);
+    }
+};
+Base64Type = __decorate([
+    SimpleType({
+        description: 'A stream of bytes, base64 encoded',
+        ctor: ArrayBuffer
+    })
+], Base64Type);
+export { Base64Type };

package/esm/document/data-type/builtin/bigint.type.d.ts

@@ -0,0 +1,6 @@
+export declare class BigIntType {
+    decode(v: any): bigint | undefined;
+    encode(v: any): string | undefined;
+    coerce(v: any): bigint | undefined;
+    validate(v: any): void;
+}

package/esm/document/data-type/builtin/bigint.type.js

@@ -0,0 +1,30 @@
+import { __decorate } from "tslib";
+import { SimpleType } from '../simple-type.js';
+const BigIntConstructor = Object.getPrototypeOf(BigInt(0)).constructor;
+let BigIntType = class BigIntType {
+    decode(v) {
+        if (v == null)
+            return v;
+        return typeof v === 'bigint' ? v : BigInt(v);
+    }
+    encode(v) {
+        if (v == null)
+            return v;
+        return typeof v === 'bigint' ? String(v) : undefined;
+    }
+    coerce(v) {
+        return this.decode(v);
+    }
+    validate(v) {
+        if (!((typeof v === 'number' && !isNaN(v)) || typeof v === 'bigint'))
+            throw new TypeError(`Invalid number value "${v}"`);
+    }
+};
+BigIntType = __decorate([
+    SimpleType({
+        name: 'bigint',
+        description: 'BigInt number',
+        ctor: BigIntConstructor
+    })
+], BigIntType);
+export { BigIntType };

package/esm/document/data-type/builtin/boolean.type.d.ts

@@ -0,0 +1,5 @@
+export declare class BooleanType {
+    decode(v: any): boolean | undefined;
+    encode(v: any): boolean | undefined;
+    coerce(v: any): boolean | undefined;
+}

package/esm/document/data-type/builtin/boolean.type.js

@@ -0,0 +1,25 @@
+import { __decorate } from "tslib";
+import { toBoolean } from 'putil-varhelpers';
+import { SimpleType } from '../simple-type.js';
+let BooleanType = class BooleanType {
+    decode(v) {
+        if (v == null)
+            return v;
+        return toBoolean(v);
+    }
+    encode(v) {
+        if (v == null)
+            return v;
+        return toBoolean(v);
+    }
+    coerce(v) {
+        return this.decode(v);
+    }
+};
+BooleanType = __decorate([
+    SimpleType({
+        description: 'Simple true/false value',
+        ctor: Boolean
+    })
+], BooleanType);
+export { BooleanType };

package/esm/document/data-type/builtin/date.type.d.ts

@@ -0,0 +1,4 @@
+import { TimestampType } from './timestamp.type.js';
+export declare class DateType extends TimestampType {
+    format: string;
+}

package/esm/document/data-type/builtin/date.type.js

@@ -0,0 +1,15 @@
+import { __decorate } from "tslib";
+import { SimpleType } from '../simple-type.js';
+import { TimestampType } from './timestamp.type.js';
+let DateType = class DateType extends TimestampType {
+    constructor() {
+        super(...arguments);
+        this.format = 'YYYY-MM-DD';
+    }
+};
+DateType = __decorate([
+    SimpleType({
+        description: 'full-date notation as defined by RFC 3339, section 5.6, for example, 2021-04-18',
+    })
+], DateType);
+export { DateType };

package/esm/document/data-type/builtin/guid.type.d.ts

@@ -0,0 +1,7 @@
+import { StringType } from './string.type.js';
+export declare class GuidType extends StringType {
+    decode(v: any): string | undefined;
+    encode(v: any): string | undefined;
+    coerce(v: any): string | undefined;
+    validate(v: string): void;
+}

package/esm/document/data-type/builtin/guid.type.js

@@ -0,0 +1,32 @@
+import { __decorate } from "tslib";
+import { toString } from 'putil-varhelpers';
+import { SimpleType } from '../simple-type.js';
+import { StringType } from './string.type.js';
+const GUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+let GuidType = class GuidType extends StringType {
+    decode(v) {
+        if (v == null)
+            return v;
+        const s = toString(v);
+        if (s)
+            this.validate(s);
+        return s;
+    }
+    encode(v) {
+        return this.decode(v);
+    }
+    coerce(v) {
+        return this.decode(v);
+    }
+    validate(v) {
+        // noinspection SuspiciousTypeOfGuard
+        if (typeof v === 'string' && !GUID_PATTERN.test(v))
+            throw new TypeError(`Invalid GUID value "${v}"`);
+    }
+};
+GuidType = __decorate([
+    SimpleType({
+        description: 'A Globally Unique Identifier (GUID) value',
+    })
+], GuidType);
+export { GuidType };

package/esm/document/data-type/builtin/index.d.ts

@@ -0,0 +1,10 @@
+export * from './any.type.js';
+export * from './base64.type.js';
+export * from './bigint.type.js';
+export * from './boolean.type.js';
+export * from './date.type.js';
+export * from './guid.type.js';
+export * from './integer.type.js';
+export * from './number.type.js';
+export * from './object.type.js';
+export * from './string.type.js';

package/esm/document/data-type/builtin/index.js

@@ -0,0 +1,10 @@
+export * from './any.type.js';
+export * from './base64.type.js';
+export * from './bigint.type.js';
+export * from './boolean.type.js';
+export * from './date.type.js';
+export * from './guid.type.js';
+export * from './integer.type.js';
+export * from './number.type.js';
+export * from './object.type.js';
+export * from './string.type.js';

package/esm/document/data-type/builtin/integer.type.d.ts

@@ -0,0 +1,6 @@
+import { NumberType } from './number.type.js';
+export declare class IntegerType extends NumberType {
+    decode(v: any): number | undefined;
+    encode(v: any): number | undefined;
+    coerce(v: any): number | undefined;
+}