@lakutata/core 1.0.60 → 3.0.0-beta.1

package/dist/esm/lib/ioc/LoadModules.js

@@ -0,0 +1,164 @@
+import { pathToFileURL } from 'url';
+import { Lifetime } from './Lifetime.js';
+import { RESOLVER, asClass, asFunction } from './Resolvers.js';
+import { isClass, isFunction } from './Utils.js';
+import { camelCase } from '@lakutata/utils/CamelCase';
+import { As } from '@lakutata/utils/As';
+const nameFormatters = {
+    camelCase: (s) => camelCase(s)
+};
+/**
+ * Given an array of glob strings, will call `require`
+ * on them, and call their default exported function with the
+ * container as the first parameter.
+ * @param dependencies
+ * @param globPatterns
+ * @param opts
+ */
+export function loadModules(dependencies, globPatterns, opts) {
+    opts ??= {};
+    const container = dependencies.container;
+    opts = optsWithDefaults(opts);
+    const modules = dependencies.listModules(globPatterns, opts);
+    if (opts.esModules) {
+        return loadEsModules(dependencies, container, modules, opts);
+    }
+    else {
+        const result = modules.map((m) => {
+            const loaded = dependencies.require(m.path);
+            return parseLoadedModule(loaded, m);
+        });
+        return registerModules(result, container, modules, opts);
+    }
+}
+/**
+ * Loads the modules using native ES6 modules and the async import()
+ * @param dependencies
+ * @param container
+ * @param modules
+ * @param opts
+ */
+async function loadEsModules(dependencies, container, modules, opts) {
+    const importPromises = [];
+    for (const m of modules) {
+        const fileUrl = pathToFileURL(m.path).toString();
+        importPromises.push(As(dependencies.require(fileUrl)));
+    }
+    const imports = await Promise.all(importPromises);
+    const result = [];
+    for (let i = 0; i < modules.length; i++) {
+        result.push(As(parseLoadedModule(imports[i], modules[i])));
+    }
+    return registerModules(result, container, modules, opts);
+}
+/**
+ * Parses the module which has been required
+ *
+ * @param {any} loaded
+ * @param {ModuleDescriptor} m
+ */
+function parseLoadedModule(loaded, m) {
+    const items = [];
+    if (!loaded)
+        return items;
+    if (isFunction(loaded)) {
+        // for module.exports = ...
+        items.push({
+            name: m.name,
+            path: m.path,
+            value: loaded,
+            opts: m.opts
+        });
+        return items;
+    }
+    if (loaded.default && isFunction(loaded.default)) {
+        // ES6 default export
+        items.push({
+            name: m.name,
+            path: m.path,
+            value: loaded.default,
+            opts: m.opts
+        });
+    }
+    // loop through non-default exports, but require the RESOLVER property set for
+    // it to be a valid service module export.
+    for (const key of Object.keys(loaded)) {
+        if (key === 'default')
+            continue;
+        if (isFunction(loaded[key]) && RESOLVER in loaded[key]) {
+            items.push({
+                name: key,
+                path: m.path,
+                value: loaded[key],
+                opts: m.opts
+            });
+        }
+    }
+    return items;
+}
+/**
+ * Registers the modules
+ * @param modulesToRegister
+ * @param container
+ * @param modules
+ * @param opts
+ */
+function registerModules(modulesToRegister, container, modules, opts) {
+    modulesToRegister
+        .reduce((acc, cur) => acc.concat(cur), [])
+        .filter((x) => x)
+        .forEach(registerDescriptor.bind(null, container, opts));
+    return {
+        loadedModules: modules
+    };
+}
+/**
+ * Returns a new options object with defaults applied.
+ * @param opts
+ */
+function optsWithDefaults(opts) {
+    return {
+        resolverOptions: {
+            lifetime: Lifetime.TRANSIENT,
+            ...(opts && opts.resolverOptions)
+        },
+        ...opts
+    };
+}
+/**
+ * Given a module descriptor, reads it and registers it's value with the container.
+ * @param container
+ * @param opts
+ * @param moduleDescriptor
+ */
+function registerDescriptor(container, opts, moduleDescriptor) {
+    const inlineConfig = moduleDescriptor.value[RESOLVER];
+    let name = inlineConfig && inlineConfig.name;
+    if (!name) {
+        name = moduleDescriptor.name;
+        let formatter = opts.formatName;
+        if (formatter) {
+            if (typeof formatter === 'string') {
+                formatter = nameFormatters[formatter];
+            }
+            if (formatter) {
+                name = formatter(name, moduleDescriptor);
+            }
+        }
+    }
+    let moduleDescriptorOpts = moduleDescriptor.opts;
+    if (typeof moduleDescriptorOpts === 'string') {
+        moduleDescriptorOpts = { lifetime: moduleDescriptorOpts };
+    }
+    const regOpts = {
+        ...opts.resolverOptions,
+        ...moduleDescriptorOpts,
+        ...inlineConfig
+    };
+    const reg = regOpts.register
+        ? regOpts.register
+        : isClass(moduleDescriptor.value)
+            ? asClass
+            : asFunction;
+    container.register(name, reg(moduleDescriptor.value, regOpts));
+}

package/dist/esm/lib/ioc/ObjectLifetime.js

@@ -0,0 +1,34 @@
+import { DI_TARGET_CONSTRUCTOR_LIFETIME, DI_TARGET_CONSTRUCTOR_LIFETIME_LOCK } from '../../constants/DIMetadataKey.js';
+import { LifetimeLockedException } from '../../exceptions/di/LifetimeLockedException.js';
+/**
+ * Get Object's lifetime
+ * @param target
+ * @constructor
+ */
+export function getObjectLifetime(target) {
+    return Reflect.getMetadata(DI_TARGET_CONSTRUCTOR_LIFETIME, target);
+}
+/**
+ * Get whether Object's lifetime is locked
+ * @param target
+ * @constructor
+ */
+export function getObjectLifetimeLocked(target) {
+    return !!Reflect.getMetadata(DI_TARGET_CONSTRUCTOR_LIFETIME_LOCK, target);
+}
+/**
+ * Set Object's lifetime
+ * @param target
+ * @param lifetime
+ * @param lock
+ * @constructor
+ */
+export function setObjectLifetime(target, lifetime, lock = false) {
+    //A locked lifetime can be declared again, but never changed
+    if (getObjectLifetimeLocked(target) && getObjectLifetime(target) !== lifetime)
+        throw new LifetimeLockedException('[{0}] Object lifecycle settings cannot be applied because the parent object lifecycle of the current operation object is locked', [target.name]);
+    if (lock)
+        Reflect.defineMetadata(DI_TARGET_CONSTRUCTOR_LIFETIME_LOCK, true, target);
+    Reflect.defineMetadata(DI_TARGET_CONSTRUCTOR_LIFETIME, lifetime, target);
+    return target;
+}

package/dist/esm/lib/ioc/ObjectWeakRefs.js

@@ -0,0 +1,42 @@
+import { As } from '@lakutata/utils/As';
+const OWR_SYMBOL = Symbol('OWR'); //Object Weak Ref
+const OFR_SYMBOL = Symbol('OFR'); //Object Finalization Registry
+/**
+ * Get object weak refs
+ * @param target
+ * @constructor
+ */
+export function getObjectWeakRefs(target) {
+    if (!Reflect.hasOwnMetadata(OFR_SYMBOL, target))
+        Reflect.defineMetadata(OFR_SYMBOL, new FinalizationRegistry((ref) => {
+            const objectWeakRefs = Reflect.getOwnMetadata(OWR_SYMBOL, target) || new Set();
+            objectWeakRefs.delete(ref);
+            Reflect.defineMetadata(OWR_SYMBOL, objectWeakRefs, target);
+        }), target);
+    if (!Reflect.hasOwnMetadata(OWR_SYMBOL, target))
+        Reflect.defineMetadata(OWR_SYMBOL, new Set(), target);
+    return Reflect.getOwnMetadata(OWR_SYMBOL, target);
+}
+/**
+ * Append object weak refs
+ * @param target
+ * @param instance
+ * @constructor
+ */
+export function appendObjectWeakRefs(target, instance) {
+    const refs = getObjectWeakRefs(target);
+    const ref = new WeakRef(instance);
+    As(Reflect.getOwnMetadata(OFR_SYMBOL, target)).register(instance, ref);
+    refs.add(ref);
+    Reflect.defineMetadata(OWR_SYMBOL, refs, target);
+}
+/**
+ * Clear transient object weak refs
+ * @param target
+ * @constructor
+ */
+export function clearObjectWeakRefs(target) {
+    if (!Reflect.hasOwnMetadata(OWR_SYMBOL, target))
+        return;
+    Reflect.deleteMetadata(OWR_SYMBOL, target);
+}

package/dist/esm/lib/ioc/Resolvers.js

@@ -0,0 +1,242 @@
+import { DependencyInjectionTypeError } from './Errors.js';
+import { Lifetime } from './Lifetime.js';
+import { isFunction, uniq } from './Utils.js';
+/**
+ * RESOLVER symbol can be used by modules loaded by
+ * `loadModules` to configure their lifetime, injection mode, etc.
+ */
+export const RESOLVER = Symbol('Dependency Injection Resolver Config');
+/**
+ * Creates a simple value resolver where the given value will always be resolved. The value is
+ * marked as leak-safe since in strict mode, the value will only be resolved when it is not leaking
+ * upwards from a child scope to a parent singleton.
+ *
+ * @param  {string} name The name to register the value as.
+ *
+ * @param  {*} value The value to resolve.
+ *
+ * @return {object} The resolver.
+ */
+export function asValue(value) {
+    return {
+        resolve: () => value,
+        isLeakSafe: true
+    };
+}
+/**
+ * Creates a factory resolver, where the given factory function
+ * will be invoked with `new` when requested.
+ *
+ * @param  {string} name
+ * The name to register the value as.
+ *
+ * @param  {Function} fn
+ * The function to register.
+ *
+ * @param {object} opts
+ * Additional options for the resolver.
+ *
+ * @return {object}
+ * The resolver.
+ */
+export function asFunction(fn, opts) {
+    if (!isFunction(fn)) {
+        throw new DependencyInjectionTypeError('asFunction', 'fn', 'function', fn);
+    }
+    const defaults = {
+        lifetime: Lifetime.TRANSIENT
+    };
+    opts = makeOptions(defaults, opts, fn[RESOLVER]);
+    const resolve = generateResolve(fn);
+    const result = {
+        resolve,
+        ...opts
+    };
+    return createDisposableResolver(createBuildResolver(result));
+}
+/**
+ * Like a factory resolver, but for classes that require `new`.
+ *
+ * @param  {string} name
+ * The name to register the value as.
+ *
+ * @param  {Class} Type
+ * The function to register.
+ *
+ * @param {object} opts
+ * Additional options for the resolver.
+ *
+ * @return {object}
+ * The resolver.
+ */
+export function asClass(Type, opts) {
+    if (!isFunction(Type)) {
+        throw new DependencyInjectionTypeError('asClass', 'Type', 'class', Type);
+    }
+    const defaults = {
+        lifetime: Lifetime.TRANSIENT
+    };
+    opts = makeOptions(defaults, opts, Type[RESOLVER]);
+    // A function to handle object construction for us, as to make the generateResolve more reusable
+    const newClass = function newClass(...args) {
+        return Reflect.construct(Type, args);
+    };
+    const resolve = generateResolve(newClass);
+    return createDisposableResolver(createBuildResolver({
+        ...opts,
+        resolve
+    }));
+}
+/**
+ * Given an options object, creates a fluid interface
+ * to manage it.
+ *
+ * @param {*} obj
+ * The object to return.
+ *
+ * @return {object}
+ * The interface.
+ */
+function createBuildResolver(obj) {
+    function setLifetime(value) {
+        return createBuildResolver({
+            ...this,
+            lifetime: value
+        });
+    }
+    function inject(injector) {
+        return createBuildResolver({
+            ...this,
+            injector
+        });
+    }
+    return updateResolver(obj, {
+        setLifetime,
+        inject,
+        transient: partial(setLifetime, Lifetime.TRANSIENT),
+        scoped: partial(setLifetime, Lifetime.SCOPED),
+        singleton: partial(setLifetime, Lifetime.SINGLETON)
+    });
+}
+/**
+ * Given a resolver, returns an object with methods to manage the disposer
+ * function.
+ * @param obj
+ */
+function createDisposableResolver(obj) {
+    function disposer(dispose) {
+        return createDisposableResolver({
+            ...this,
+            dispose
+        });
+    }
+    return updateResolver(obj, {
+        disposer
+    });
+}
+/**
+ * Partially apply arguments to the given function.
+ */
+function partial(fn, arg1) {
+    return function partiallyApplied() {
+        return fn.call(this, arg1);
+    };
+}
+/**
+ * Makes an options object based on defaults.
+ *
+ * @param  {object} defaults
+ * Default options.
+ *
+ * @param  {...} rest
+ * The input to check and possibly assign to the resulting object
+ *
+ * @return {object}
+ */
+function makeOptions(defaults, ...rest) {
+    return Object.assign({}, defaults, ...rest);
+}
+/**
+ * Creates a new resolver with props merged from both.
+ *
+ * @param source
+ * @param target
+ */
+function updateResolver(source, target) {
+    const result = {
+        ...source,
+        ...target
+    };
+    return result;
+}
+/**
+ * Returns a new Proxy that checks the result from `injector`
+ * for values before delegating to the actual container.
+ * @param container cradle
+ * @param injector injector
+ */
+function createInjectorProxy(container, injector) {
+    const locals = injector(container);
+    const allKeys = uniq([
+        ...Reflect.ownKeys(container.cradle),
+        ...Reflect.ownKeys(locals)
+    ]);
+    // Need to refactor.
+    const proxy = new Proxy({}, {
+        /**
+         * Resolves the value by first checking the locals, then the container.
+         */
+        get(target, name) {
+            if (name === Symbol.iterator) {
+                return function* iterateRegistrationsAndLocals() {
+                    for (const prop in container.cradle) {
+                        yield prop;
+                    }
+                    for (const prop in locals) {
+                        yield prop;
+                    }
+                };
+            }
+            if (name in locals) {
+                return locals[name];
+            }
+            return container.resolve(name);
+        },
+        /**
+         * Used for `Object.keys`.
+         */
+        ownKeys() {
+            return allKeys;
+        },
+        /**
+         * Used for `Object.keys`.
+         */
+        getOwnPropertyDescriptor(target, key) {
+            if (allKeys.indexOf(key) > -1) {
+                return {
+                    enumerable: true,
+                    configurable: true
+                };
+            }
+            return undefined;
+        }
+    });
+    return proxy;
+}
+/**
+ * Returns a resolve function used to construct the dependency graph
+ * @description Dependencies are always provided through the cradle proxy (lakutata declares them with decorators),
+ * so the construction target is never parsed for its parameter names
+ * @param fn The function to construct
+ */
+function generateResolve(fn) {
+    // Use a regular function instead of an arrow function to facilitate binding to the resolver.
+    return function resolve(container) {
+        // If we have a custom injector, we need to wrap the cradle.
+        const cradle = this.injector
+            ? createInjectorProxy(container, this.injector)
+            : container.cradle;
+        // Return the target injected with the cradle
+        return fn(cradle);
+    };
+}

package/dist/esm/lib/ioc/Utils.js

@@ -0,0 +1,65 @@
+import { isSymbol } from '@lakutata/utils/IsSymbol';
+import { As } from '@lakutata/utils/As';
+/**
+ * Quick flatten utility to flatten a 2-dimensional array.
+ * @param array
+ */
+export function flatten(array) {
+    const result = [];
+    array.forEach((arr) => {
+        arr.forEach((item) => {
+            result.push(item);
+        });
+    });
+    return result;
+}
+/**
+ * Creates a { name: value } object if the input isn't already in that format.
+ * @param name
+ * @param value
+ */
+export function nameValueToObject(name, value) {
+    const obj = name;
+    if (typeof obj === 'string' || isSymbol(obj))
+        return { [name]: value };
+    return As(obj);
+}
+/**
+ * Returns the last item in the array.
+ * @param arr
+ */
+export function last(arr) {
+    return arr[arr.length - 1];
+}
+/**
+ * Determines if the given function is a class.
+ * @param fn
+ */
+export function isClass(fn) {
+    if (typeof fn !== 'function')
+        return false;
+    //Arrow, async and method functions have no prototype, so they are never constructors
+    const prototypeDescriptor = Object.getOwnPropertyDescriptor(fn, 'prototype');
+    if (!prototypeDescriptor)
+        return false;
+    //The prototype of a class (and of built-in constructors) is read-only, unlike the one of a plain function
+    if (!prototypeDescriptor.writable)
+        return true;
+    //A plain function named in PascalCase is treated as an ES5 constructor function
+    return !!fn.name && fn.name[0] === fn.name[0].toUpperCase();
+}
+/**
+ * Determines if the given value is a function.
+ * @param val
+ */
+export function isFunction(val) {
+    return typeof val === 'function';
+}
+/**
+ * Returns the unique items in the array.
+ * The array to remove dupes from.
+ * @param arr
+ */
+export function uniq(arr) {
+    return Array.from(new Set(arr));
+}

package/dist/esm/lib/validation/JsonSchema.js

@@ -0,0 +1,81 @@
+import { DefaultValidationOptions } from './VLD.js';
+import { SchemaConversionException } from './exceptions/SchemaConversionException.js';
+import { JsonDraft04SchemaParser, JsonDraft201909SchemaParser, JsonDraft202012SchemaParser, JsonSchemaParser, OpenApi31SchemaParser, OpenApiSchemaParser } from './engine/json-schema/index.js';
+import { fromJsonSchema as importJsonSchema } from './engine/json-schema/import.js';
+/**
+ * The parsers of the versions
+ */
+const parsers = {
+    'draft-2020-12': JsonDraft202012SchemaParser,
+    'draft-2019-09': JsonDraft201909SchemaParser,
+    'draft-07': JsonSchemaParser,
+    'draft-04': JsonDraft04SchemaParser,
+    'openapi-3.0': OpenApiSchemaParser,
+    'openapi-3.1': OpenApi31SchemaParser
+};
+/**
+ * Converts a schema (or a DTO class) into a JSON Schema, for an API document or another validator. The JSON Schema
+ * describes the values the schema accepts without conversion: what cannot be expressed (custom rules, references to
+ * other values, conversions) is dropped, so the JSON Schema may accept more values, never less. The formats are named
+ * after the rules (their implementations differ on edge cases), and the numbers beyond the safe integers are accepted.
+ * @param source The schema, or the DTO class, to convert.
+ * @param options The JSON Schema version and the validation options the schema is used with.
+ * @returns A new JSON Schema.
+ * @throws {SchemaConversionException} When the source is not a schema nor a DTO class, or the target is unknown.
+ * @example
+ * ```typescript
+ * import {DTO, type JSONSchema} from 'lakutata'
+ * import {toJsonSchema} from 'lakutata/dtos'
+ *
+ * const schema: JSONSchema = toJsonSchema(DTO.Object({
+ *     name: DTO.String().max(64).required(),
+ *     age: DTO.Number().integer().min(0)
+ * }), {target: 'openapi-3.1'})
+ * //{type: 'object', properties: {name: {type: 'string', maxLength: 64, …}, age: {type: 'integer', minimum: 0}}, required: ['name'], …}
+ * console.log(schema)
+ * ```
+ */
+export function toJsonSchema(source, options = {}) {
+    const schema = typeof source === 'function' && typeof source.Schema === 'function' ? source.Schema() : source;
+    if (!schema || typeof schema.describe !== 'function')
+        throw new SchemaConversionException('Not a schema object.');
+    const target = options.target || 'draft-2020-12';
+    const Parser = parsers[target];
+    if (!Parser)
+        throw new SchemaConversionException(`Unknown JSON Schema target: ${target}`);
+    const parser = new Parser({
+        includeSchemaDialect: !!options.dialect,
+        preferences: { ...(options.preferences || DefaultValidationOptions) }
+    });
+    const definitions = (options.definitions || {});
+    const result = parser.parse(schema.describe(), definitions);
+    return result;
+}
+/**
+ * Converts a JSON Schema (drafts 04 to 2020-12, or an OpenAPI 3.0/3.1 schema object) into a schema, which validates
+ * like JSON Schema: without conversion, the unknown keys as `additionalProperties` says, the formats like the full
+ * formats of ajv-formats, and the keywords next to a `$ref` applied (like ajv). The `default` values are applied.
+ * @param schema The JSON Schema, or a boolean schema (true accepts every value, false none).
+ * @param options The version of the JSON Schema, and where its references are resolved.
+ * @returns The schema, to validate with `DTO.validate()` or to use in a DTO.
+ * @throws {SchemaConversionException} When the JSON Schema is not an object nor a boolean, a reference cannot be
+ * resolved, or a pattern is not a valid regular expression.
+ * @example
+ * ```typescript
+ * import {DTO, type Schema} from 'lakutata'
+ * import {fromJsonSchema} from 'lakutata/dtos'
+ *
+ * const schema: Schema = fromJsonSchema({
+ *     type: 'object',
+ *     properties: {
+ *         name: {type: 'string'},
+ *         age: {type: 'integer', minimum: 0, default: 18}
+ *     },
+ *     required: ['name']
+ * })
+ * console.log(DTO.validate({name: 'Ada'}, schema)) //{name: 'Ada', age: 18}
+ * ```
+ */
+export function fromJsonSchema(schema, options = {}) {
+    return importJsonSchema(schema, options);
+}