@opra/common 0.25.4 → 0.26.0

package/esm/document/factory/api-document-factory.js

@@ -0,0 +1,227 @@
+import { cloneObject, resolveThunk, ResponsiveMap } from '../../helpers/index.js';
+import { OpraSchema } from '../../schema/index.js';
+import { ApiDocument } from '../api-document.js';
+import { RESOURCE_METADATA } from '../constants.js';
+import { ComplexType } from '../data-type/complex-type.js';
+import { EnumType } from '../data-type/enum-type.js';
+import { Collection } from '../resource/collection.js';
+import { Container } from '../resource/container.js';
+import { Singleton } from '../resource/singleton.js';
+import { Storage } from '../resource/storage.js';
+import { TypeDocumentFactory } from './type-document-factory.js';
+/**
+ * @class ApiDocumentFactory
+ */
+export class ApiDocumentFactory extends TypeDocumentFactory {
+    constructor() {
+        super(...arguments);
+        this.resourceQueue = new ResponsiveMap();
+    }
+    /**
+     * Creates ApiDocument instance from given schema object
+     * @param init
+     */
+    static async createDocument(init) {
+        const factory = new ApiDocumentFactory();
+        const document = factory.document = new ApiDocument();
+        await factory.initDocument(init);
+        return document;
+    }
+    /**
+     * Downloads schema from the given URL and creates the document instance   * @param url
+     */
+    static async createDocumentFromUrl(url) {
+        const factory = new ApiDocumentFactory();
+        const document = factory.document = new ApiDocument();
+        await factory.initDocumentFromUrl(url);
+        return document;
+    }
+    async initDocument(init) {
+        await super.initDocument(init);
+        const processContainer = async (container, containerInit) => {
+            if (!containerInit.resources)
+                return;
+            if (Array.isArray(containerInit.resources)) {
+                for (const thunk of containerInit.resources) {
+                    const initArguments = await this.importResourceInstance(thunk);
+                    container.resources.set(initArguments.name, await this.createResource(container, initArguments));
+                }
+            }
+            else
+                for (const [name, schema] of Object.entries(containerInit.resources)) {
+                    const initArguments = await this.importResourceSchema(name, schema);
+                    container.resources.set(initArguments.name, await this.createResource(container, initArguments));
+                }
+            container.resources.sort();
+        };
+        if (init.root) {
+            this.curPath.push('/root');
+            await processContainer(this.document.root, init.root);
+            this.curPath.pop();
+            this.document.invalidate();
+        }
+        return this.document;
+    }
+    async importResourceSchema(name, schema) {
+        const convertEndpoints = async (source) => {
+            if (!source)
+                return;
+            const output = {};
+            for (const [kA, oA] of Object.entries(source)) {
+                /* istanbul ignore next */
+                if (!oA)
+                    continue;
+                let parameters;
+                if (oA.parameters) {
+                    parameters = {};
+                    for (const [kP, oP] of Object.entries(oA.parameters)) {
+                        if (oP.enum) {
+                            oP.type = EnumType(oP.enum, { name: kP + 'Enum' });
+                        }
+                        parameters[kP] = {
+                            ...oP,
+                            type: await this.importDataType(oP.type || 'any')
+                        };
+                    }
+                }
+                output[kA] = { ...oA[kA], parameters };
+            }
+            return output;
+        };
+        if (schema.kind === 'Collection') {
+            return {
+                ...schema,
+                kind: schema.kind,
+                name,
+                type: await this.importDataType(schema.type),
+                actions: await convertEndpoints(schema.actions),
+                operations: await convertEndpoints(schema.operations),
+            };
+        }
+        else if (schema.kind === 'Singleton') {
+            return {
+                ...schema,
+                kind: schema.kind,
+                name,
+                type: await this.importDataType(schema.type),
+                actions: await convertEndpoints(schema.actions),
+                operations: await convertEndpoints(schema.operations),
+            };
+        }
+        else if (schema.kind === 'Storage') {
+            return {
+                ...schema,
+                name,
+                actions: await convertEndpoints(schema.actions),
+                operations: await convertEndpoints(schema.operations),
+            };
+        }
+        else if (schema.kind === 'Container') {
+            const resources = [];
+            if (schema.resources) {
+                for (const [k, o] of Object.entries(schema.resources)) {
+                    const rinit = await this.importResourceSchema(k, o);
+                    resources.push(rinit);
+                }
+            }
+            return {
+                ...schema,
+                name,
+                resources,
+                actions: await convertEndpoints(schema.actions)
+            };
+        }
+        throw new TypeError(`Can not import resource schema (${schema.kind})`);
+    }
+    async importResourceInstance(thunk) {
+        thunk = await resolveThunk(thunk);
+        let ctor;
+        let metadata;
+        let instance;
+        if (typeof thunk === 'function') {
+            ctor = thunk;
+        }
+        else {
+            ctor = Object.getPrototypeOf(thunk).constructor;
+            instance = thunk;
+            if (!Reflect.hasMetadata(RESOURCE_METADATA, ctor) &&
+                OpraSchema.isResource(thunk) && typeof thunk.controller === 'object') {
+                ctor = Object.getPrototypeOf(thunk.controller).constructor;
+                metadata = thunk;
+                instance = thunk.controller;
+            }
+        }
+        metadata = metadata || Reflect.getMetadata(RESOURCE_METADATA, ctor);
+        if (!metadata && OpraSchema.isResource(metadata))
+            throw new TypeError(`Class "${ctor.name}" doesn't have a valid Resource metadata`);
+        const convertEndpoints = async (source) => {
+            if (!source)
+                return;
+            const output = {};
+            for (const [kA, oA] of Object.entries(source)) {
+                let parameters;
+                if (oA.parameters) {
+                    parameters = {};
+                    for (const [kP, oP] of Object.entries(oA.parameters)) {
+                        if (oP.enum) {
+                            oP.type = EnumType(oP.enum, { name: kP + 'Enum' });
+                        }
+                        parameters[kP] = {
+                            ...oP,
+                            type: await this.importDataType(oP.type || 'any')
+                        };
+                    }
+                }
+                output[kA] = { ...oA, parameters };
+            }
+            return output;
+        };
+        // Clone metadata to prevent changing its contents
+        const initArguments = cloneObject(metadata);
+        initArguments.controller = instance;
+        initArguments.ctor = ctor;
+        if (initArguments.actions)
+            initArguments.actions = await convertEndpoints(initArguments.actions);
+        if (initArguments.kind === 'Collection' || initArguments.kind === 'Singleton') {
+            const dataType = await this.importDataType((metadata).type);
+            if (!dataType)
+                throw new TypeError(`Unable to determine data type of "${initArguments.name}" resource`);
+            if (!(dataType instanceof ComplexType))
+                throw new TypeError(`Data type of "${initArguments.name}" resource is not a ComplexType`);
+            initArguments.type = dataType;
+            if (initArguments.operations)
+                initArguments.operations = await convertEndpoints(initArguments.operations);
+        }
+        else if (initArguments.kind === 'Container') {
+            const oldResources = initArguments.resources;
+            if (Array.isArray(oldResources)) {
+                initArguments.resources = [];
+                for (const t of oldResources) {
+                    const rinit = await this.importResourceInstance(t);
+                    initArguments.resources.push(rinit);
+                }
+            }
+        }
+        return initArguments;
+    }
+    async createResource(container, initArguments) {
+        if (initArguments.kind === 'Collection')
+            return new Collection(container, initArguments);
+        if (initArguments.kind === 'Singleton')
+            return new Singleton(container, initArguments);
+        if (initArguments.kind === 'Storage')
+            return new Storage(container, initArguments);
+        if (initArguments.kind === 'Container') {
+            const newContainer = new Container(container, { ...initArguments, resources: undefined });
+            if (initArguments.resources) {
+                for (const r of initArguments.resources) {
+                    const res = await this.createResource(newContainer, r);
+                    newContainer.resources.set(res.name, res);
+                }
+            }
+            return newContainer;
+        }
+        else
+            throw new Error(`Unknown resource type ${initArguments.kind}`);
+    }
+}

package/esm/document/factory/type-document-factory.js

@@ -0,0 +1,320 @@
+import { validator } from 'valgen';
+import { cloneObject, isConstructor, resolveThunk, ResponsiveMap } from '../../helpers/index.js';
+import { OpraSchema } from '../../schema/index.js';
+import { DATATYPE_METADATA } from '../constants.js';
+import { AnyType, Base64Type, BigintType, BooleanType, DateType, IntegerType, NullType, NumberType, ObjectIdType, ObjectType, StringType, TimestampType, TimeType, UuidType } from '../data-type/builtin/index.js';
+import { ComplexType } from '../data-type/complex-type.js';
+import { EnumType } from '../data-type/enum-type.js';
+import { MappedType } from '../data-type/mapped-type.js';
+import { SimpleType } from '../data-type/simple-type.js';
+import { UnionType } from '../data-type/union-type.js';
+import { TypeDocument } from '../type-document.js';
+/**
+ * @class TypeDocumentFactory
+ */
+export class TypeDocumentFactory {
+    constructor() {
+        this.typeQueue = new ResponsiveMap();
+        this.circularRefs = new Map();
+        this.curPath = [];
+        this.cache = new Map();
+    }
+    /**
+     * Creates ApiDocument instance from given schema object
+     */
+    static async createDocument(init) {
+        const factory = new TypeDocumentFactory();
+        const document = factory.document = new TypeDocument();
+        await factory.initDocument(init);
+        return document;
+    }
+    /**
+     * Downloads schema from the given URL and creates the document instance   * @param url
+     */
+    static async createDocumentFromUrl(url) {
+        const factory = new TypeDocumentFactory();
+        const document = factory.document = new TypeDocument();
+        await factory.initDocumentFromUrl(url);
+        return document;
+    }
+    async initDocument(init) {
+        this.document.url = init.url;
+        if (init.info)
+            Object.assign(this.document.info, init.info);
+        if (!init?.noBuiltinTypes) {
+            const builtinDocument = await this.createBuiltinTypeDocument();
+            this.document.references.set('Opra', builtinDocument);
+        }
+        if (init.references)
+            await this.addReferences(init.references);
+        if (init.types) {
+            this.curPath.push('Types->');
+            // Add type sources into typeQueue
+            if (Array.isArray(init.types)) {
+                let i = 0;
+                for (const thunk of init.types) {
+                    const metadata = Reflect.getMetadata(DATATYPE_METADATA, thunk) || thunk[DATATYPE_METADATA];
+                    if (!(metadata && metadata.name))
+                        throw new TypeError(`Metadata information not found at types[${i++}] "${String(thunk)}"`);
+                    this.typeQueue.set(metadata.name, thunk);
+                }
+            }
+            else
+                for (const [name, schema] of Object.entries(init.types)) {
+                    this.typeQueue.set(name, { ...schema, name });
+                }
+            // Create type instances
+            for (const thunk of this.typeQueue.values()) {
+                await this.importDataType(thunk);
+            }
+            this.document.types.sort();
+            this.curPath.pop();
+        }
+        this.document.invalidate();
+        return this.document;
+    }
+    async initDocumentFromUrl(url) {
+        const resp = await fetch(url, { method: 'GET' });
+        const init = await resp.json();
+        if (!init)
+            throw new TypeError(`Invalid response returned from url: ${url}`);
+        return await this.initDocument({ ...init, url });
+    }
+    async createBuiltinTypeDocument() {
+        const init = {
+            version: OpraSchema.SpecVersion,
+            info: {
+                version: OpraSchema.SpecVersion,
+                title: 'Opra built-in types',
+                contact: [{
+                        url: 'https://github.com/oprajs/opra'
+                    }
+                ],
+                license: {
+                    url: 'https://github.com/oprajs/opra/blob/main/LICENSE',
+                    name: 'MIT'
+                }
+            },
+            types: [AnyType, Base64Type, BigintType, BooleanType,
+                DateType, UuidType, IntegerType, NullType,
+                NumberType, ObjectType, ObjectIdType, StringType,
+                TimeType, TimestampType
+            ]
+        };
+        const factory = new TypeDocumentFactory();
+        factory.document = new TypeDocument();
+        return await factory.initDocument({ ...init, noBuiltinTypes: true });
+    }
+    async addReferences(references) {
+        const { document } = this;
+        for (const [ns, r] of Object.entries(references)) {
+            if (typeof r === 'string') {
+                document.references.set(ns, await this.initDocumentFromUrl(r));
+            }
+            else if (r instanceof TypeDocument)
+                document.references.set(ns, r);
+            else if (typeof r === 'object') {
+                document.references.set(ns, await this.initDocument(r));
+            }
+            else
+                throw new TypeError(`Invalid document reference (${ns}) in schema`);
+        }
+    }
+    async importDataType(thunk) {
+        thunk = await resolveThunk(thunk);
+        let name = '';
+        let schema;
+        let ctor;
+        if (typeof thunk === 'string') {
+            name = thunk;
+            schema = this.typeQueue.get(name);
+        }
+        else if (typeof thunk === 'function') {
+            const metadata = Reflect.getMetadata(DATATYPE_METADATA, thunk);
+            if (!metadata) {
+                // Check if is an internal type class like String, Number etc
+                const dataType = this.document.getDataType(thunk, true);
+                if (dataType)
+                    return dataType;
+                throw new TypeError(`Class "${thunk.name}" doesn't have a valid DataType metadata`);
+            }
+            name = metadata.name;
+            schema = metadata;
+            ctor = thunk;
+        }
+        else if (typeof thunk === 'object') {
+            if (OpraSchema.isDataType(thunk)) {
+                name = thunk.name;
+                ctor = thunk.ctor || ctor;
+                schema = thunk;
+            }
+            else {
+                // It should be an enum object
+                const metadata = thunk[DATATYPE_METADATA];
+                if (!metadata)
+                    throw new TypeError(`No EnumType metadata found for object ${JSON.stringify(thunk).substring(0, 20)}...`);
+                name = metadata.name;
+                const dataType = this.document.getDataType(name, true);
+                if (dataType)
+                    return dataType;
+                schema = cloneObject(metadata);
+            }
+        }
+        ctor = ctor ?? (schema && (isConstructor(schema.ctor)) ? schema.ctor : undefined);
+        if (name) {
+            if (this.circularRefs.has(name.toLowerCase()))
+                throw new TypeError('Circular reference detected');
+            const dataType = this.document.getDataType(name, true);
+            if (dataType)
+                return dataType;
+            this.curPath.push('/' + name);
+            this.circularRefs.set(name, 1);
+        }
+        if (ctor) {
+            if (this.circularRefs.has(ctor))
+                throw new TypeError('Circular reference detected');
+            const dataType = this.document.getDataType(ctor, true);
+            if (dataType)
+                return dataType;
+            this.circularRefs.set(ctor, 1);
+        }
+        try {
+            if (!OpraSchema.isDataType(schema))
+                throw new TypeError(`No DataType schema determined`);
+            // Create an empty DataType instance and add in to document.
+            // This will help us for circular dependent data types
+            const instance = this.createDataTypeInstance(schema.kind, name);
+            if (name)
+                this.document.types.set(name, instance);
+            const initArguments = cloneObject(schema);
+            await this.prepareDataTypeInitArguments(initArguments, ctor);
+            if (initArguments.kind === 'ComplexType')
+                ComplexType.apply(instance, [this.document, initArguments]);
+            else if (initArguments.kind === 'SimpleType')
+                SimpleType.apply(instance, [this.document, initArguments]);
+            else if (initArguments.kind === 'EnumType')
+                EnumType.apply(instance, [this.document, initArguments]);
+            else if (initArguments.kind === 'MappedType')
+                MappedType.apply(instance, [this.document, initArguments]);
+            else if (initArguments.kind === 'UnionType')
+                UnionType.apply(instance, [this.document, initArguments]);
+            else
+                throw new TypeError(`Invalid data type schema: ${String(schema)}`);
+            return instance;
+        }
+        finally {
+            if (name) {
+                this.curPath.pop();
+                this.circularRefs.delete(name.toLowerCase());
+            }
+            if (ctor)
+                this.circularRefs.delete(ctor);
+        }
+    }
+    async prepareDataTypeInitArguments(schema, ctor) {
+        const initArguments = schema;
+        // Import extending class first
+        if (initArguments.kind === 'SimpleType' || initArguments.kind === 'ComplexType' ||
+            initArguments.kind === 'EnumType') {
+            if (ctor) {
+                const baseClass = Object.getPrototypeOf(ctor.prototype).constructor;
+                const baseMeta = Reflect.getMetadata(DATATYPE_METADATA, baseClass);
+                if (baseMeta) {
+                    initArguments.base = await this.importDataType(baseClass);
+                }
+            }
+            else if (initArguments.base) {
+                initArguments.base = await this.importDataType(initArguments.base);
+            }
+        }
+        if (initArguments.kind === 'SimpleType' && ctor) {
+            if (typeof ctor.prototype.decode === 'function')
+                initArguments.decoder = initArguments.name
+                    ? validator(initArguments.name, ctor.prototype.decode) : validator(ctor.prototype.decode);
+            if (typeof ctor.prototype.encode === 'function')
+                initArguments.decoder = initArguments.name
+                    ? validator(initArguments.name, ctor.prototype.encode) : validator(ctor.prototype.encode);
+            return;
+        }
+        if (initArguments.kind === 'ComplexType') {
+            initArguments.ctor = ctor;
+            if (initArguments.fields) {
+                const srcFields = initArguments.fields;
+                const trgFields = initArguments.fields = {};
+                for (const [fieldName, o] of Object.entries(srcFields)) {
+                    try {
+                        this.curPath.push('.' + fieldName);
+                        const srcMeta = typeof o === 'string' ? { type: o } : o;
+                        const fieldInit = trgFields[fieldName] = {
+                            ...srcMeta,
+                            name: fieldName
+                        };
+                        if (srcMeta.enum) {
+                            const enumObject = srcMeta.enum;
+                            delete srcMeta.enum;
+                            if (enumObject[DATATYPE_METADATA]) {
+                                fieldInit.type = await this.importDataType(enumObject);
+                            }
+                            else {
+                                const enumMeta = EnumType(enumObject);
+                                fieldInit.type = await this.importDataType({ ...enumMeta, kind: 'EnumType', base: undefined });
+                            }
+                        }
+                        else {
+                            if (srcMeta.isArray && !srcMeta.type)
+                                throw new TypeError(`"type" must be defined explicitly for array properties`);
+                            fieldInit.type = await this.importDataType(srcMeta.type || srcMeta.designType || 'any');
+                        }
+                        this.curPath.pop();
+                    }
+                    catch (e) {
+                        e.message = `Error in resource "${initArguments.name}.${fieldName}". ` + e.message;
+                        throw e;
+                    }
+                }
+            }
+        }
+        if (initArguments.kind === 'MappedType') {
+            const dataType = await this.importDataType(initArguments.base);
+            // istanbul ignore next
+            if (!(dataType instanceof ComplexType))
+                throw new TypeError('MappedType.type property must address to a ComplexType');
+            initArguments.base = dataType;
+        }
+        if (initArguments.kind === 'UnionType') {
+            const oldTypes = initArguments.types;
+            initArguments.types = [];
+            for (const type of oldTypes)
+                initArguments.types.push(await this.importDataType(type));
+        }
+        return initArguments;
+    }
+    createDataTypeInstance(kind, name) {
+        const dataType = {
+            document: this.document,
+            kind,
+            name
+        };
+        switch (kind) {
+            case OpraSchema.ComplexType.Kind:
+                Object.setPrototypeOf(dataType, ComplexType.prototype);
+                break;
+            case OpraSchema.EnumType.Kind:
+                Object.setPrototypeOf(dataType, EnumType.prototype);
+                break;
+            case OpraSchema.MappedType.Kind:
+                Object.setPrototypeOf(dataType, MappedType.prototype);
+                break;
+            case OpraSchema.SimpleType.Kind:
+                Object.setPrototypeOf(dataType, SimpleType.prototype);
+                break;
+            case OpraSchema.UnionType.Kind:
+                Object.setPrototypeOf(dataType, UnionType.prototype);
+                break;
+            default:
+                throw new TypeError(`Unknown DataType kind (${kind})`);
+        }
+        return dataType;
+    }
+}
+TypeDocumentFactory.designTypeMap = new Map();

package/esm/document/index.js

@@ -1,7 +1,9 @@
 import 'reflect-metadata';
 export * from './constants.js';
 export * from './api-document.js';
-export * from './factory/index.js';
+export * from './type-document.js';
+export * from './factory/type-document-factory.js';
+export * from './factory/api-document-factory.js';
 export * from './data-type/data-type.js';
 export * from './data-type/complex-type.js';
 export * from './data-type/field.js';
@@ -10,9 +12,13 @@ export * from './data-type/mapped-type.js';
 export * from './data-type/simple-type.js';
 export * from './data-type/union-type.js';
 export * from './resource/resource.js';
+export * from './resource/crud-resource.js';
 export * from './resource/collection.js';
+export * from './resource/container.js';
 export * from './resource/singleton.js';
 export * from './resource/storage.js';
+export * from './resource/endpoint.js';
+export * from './resource/parameter.js';
 export * from './interfaces/collection.interface.js';
 export * from './interfaces/singleton.interface.js';
 export * from './interfaces/storage.interface.js';

package/esm/document/resource/action-decorator.js

@@ -0,0 +1,23 @@
+import { RESOURCE_METADATA } from '../constants.js';
+export function createActionDecorator(options, bannedProperties, list) {
+    const decorator = ((target, propertyKey) => {
+        if (typeof propertyKey === 'string' && bannedProperties.includes(propertyKey))
+            throw new TypeError(`The "${propertyKey}" property is reserved for "${propertyKey}" operations and cannot be used as an action'`);
+        const resourceMetadata = (Reflect.getOwnMetadata(RESOURCE_METADATA, target.constructor) || {});
+        resourceMetadata.actions = resourceMetadata.actions || {};
+        const actionMeta = { ...options };
+        resourceMetadata.actions[propertyKey] = actionMeta;
+        for (const fn of list)
+            fn(actionMeta);
+        Reflect.defineMetadata(RESOURCE_METADATA, resourceMetadata, target.constructor);
+    });
+    decorator.Parameter = (name, arg0) => {
+        const parameterOptions = typeof arg0 === 'string' || typeof arg0 === 'function' ? { type: arg0 } : { ...arg0 };
+        list.push((operationMeta) => {
+            operationMeta.parameters = operationMeta.parameters || {};
+            operationMeta.parameters[name] = { ...parameterOptions };
+        });
+        return decorator;
+    };
+    return decorator;
+}