@lakutata/core 1.0.59 → 3.0.0-beta.0

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

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOLVER = void 0;
+exports.asValue = asValue;
+exports.asFunction = asFunction;
+exports.asClass = asClass;
+const Errors_js_1 = require("./Errors.js");
+const Lifetime_js_1 = require("./Lifetime.js");
+const Utils_js_1 = require("./Utils.js");
+/**
+ * RESOLVER symbol can be used by modules loaded by
+ * `loadModules` to configure their lifetime, injection mode, etc.
+ */
+exports.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.
+ */
+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.
+ */
+function asFunction(fn, opts) {
+    if (!(0, Utils_js_1.isFunction)(fn)) {
+        throw new Errors_js_1.DependencyInjectionTypeError('asFunction', 'fn', 'function', fn);
+    }
+    const defaults = {
+        lifetime: Lifetime_js_1.Lifetime.TRANSIENT
+    };
+    opts = makeOptions(defaults, opts, fn[exports.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.
+ */
+function asClass(Type, opts) {
+    if (!(0, Utils_js_1.isFunction)(Type)) {
+        throw new Errors_js_1.DependencyInjectionTypeError('asClass', 'Type', 'class', Type);
+    }
+    const defaults = {
+        lifetime: Lifetime_js_1.Lifetime.TRANSIENT
+    };
+    opts = makeOptions(defaults, opts, Type[exports.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_js_1.Lifetime.TRANSIENT),
+        scoped: partial(setLifetime, Lifetime_js_1.Lifetime.SCOPED),
+        singleton: partial(setLifetime, Lifetime_js_1.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 = (0, Utils_js_1.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/cjs/lib/ioc/Utils.d.ts

@@ -0,0 +1,33 @@
+import { Constructor } from './Resolvers.js';
+/**
+ * Quick flatten utility to flatten a 2-dimensional array.
+ * @param array
+ */
+export declare function flatten<T>(array: Array<Array<T>>): Array<T>;
+/**
+ * Creates a { name: value } object if the input isn't already in that format.
+ * @param name
+ * @param value
+ */
+export declare function nameValueToObject(name: string | symbol | object, value?: any): Record<string | symbol, any>;
+/**
+ * Returns the last item in the array.
+ * @param arr
+ */
+export declare function last<T>(arr: Array<T>): T;
+/**
+ * Determines if the given function is a class.
+ * @param fn
+ */
+export declare function isClass(fn: Function | Constructor<any>): boolean;
+/**
+ * Determines if the given value is a function.
+ * @param val
+ */
+export declare function isFunction(val: unknown): boolean;
+/**
+ * Returns the unique items in the array.
+ * The array to remove dupes from.
+ * @param arr
+ */
+export declare function uniq<T>(arr: Array<T>): Array<T>;

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

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flatten = flatten;
+exports.nameValueToObject = nameValueToObject;
+exports.last = last;
+exports.isClass = isClass;
+exports.isFunction = isFunction;
+exports.uniq = uniq;
+const IsSymbol_1 = require("@lakutata/utils/IsSymbol");
+const As_1 = require("@lakutata/utils/As");
+/**
+ * Quick flatten utility to flatten a 2-dimensional array.
+ * @param array
+ */
+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
+ */
+function nameValueToObject(name, value) {
+    const obj = name;
+    if (typeof obj === 'string' || (0, IsSymbol_1.isSymbol)(obj))
+        return { [name]: value };
+    return (0, As_1.As)(obj);
+}
+/**
+ * Returns the last item in the array.
+ * @param arr
+ */
+function last(arr) {
+    return arr[arr.length - 1];
+}
+/**
+ * Determines if the given function is a class.
+ * @param fn
+ */
+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
+ */
+function isFunction(val) {
+    return typeof val === 'function';
+}
+/**
+ * Returns the unique items in the array.
+ * The array to remove dupes from.
+ * @param arr
+ */
+function uniq(arr) {
+    return Array.from(new Set(arr));
+}

package/dist/cjs/lib/validation/JsonSchema.d.ts

@@ -0,0 +1,127 @@
+import type { JSONSchema } from '../../types/JSONSchema.js';
+import type { Schema } from './types/Schema.js';
+import type { ValidationOptions } from './interfaces/ValidationOptions.js';
+/**
+ * The JSON Schema versions `toJsonSchema()` writes: the JSON Schema drafts, or the schema objects of OpenAPI 3.0 and
+ * 3.1.
+ */
+export type JsonSchemaTarget = 'draft-2020-12' | 'draft-2019-09' | 'draft-07' | 'draft-04' | 'openapi-3.0' | 'openapi-3.1';
+/**
+ * The options of the conversion of a schema into a JSON Schema
+ */
+export interface ToJsonSchemaOptions {
+    /**
+     * The JSON Schema version to write.
+     * @default 'draft-2020-12'
+     */
+    target?: JsonSchemaTarget;
+    /**
+     * The validation options the schema is used with: they decide which unknown keys are accepted
+     * (`additionalProperties`) and which keys are required.
+     * @default the validation options of lakutata (unknown keys allowed, keys optional)
+     */
+    preferences?: ValidationOptions;
+    /**
+     * Whether the JSON Schema declares its version with `$schema` (JSON Schema versions only, not OpenAPI).
+     * @default false
+     */
+    dialect?: boolean;
+    /**
+     * An object receiving the shared schemas (the schemas given an id with `.id()`), by id. The JSON Schema refers to
+     * them with `$ref` (`#/$defs/<id>`, `#/definitions/<id>` in draft 04, `#/components/schemas/<id>` in OpenAPI);
+     * the JSON Schema versions also embed them in the root `$defs` (`definitions`). An OpenAPI schema object cannot
+     * hold them: the OpenAPI targets return them in the root key `schemas` of the result as well, both to be moved by
+     * the caller into the `components.schemas` of its document.
+     */
+    definitions?: Record<string, JSONSchema>;
+}
+/**
+ * What `toJsonSchema()` converts: a schema, or a DTO class (the schema returned by its static `Schema()`).
+ */
+export type JsonSchemaSource = Schema | {
+    /**
+     * The object schema of the DTO class.
+     * @returns The schema.
+     */
+    Schema(): Schema;
+};
+/**
+ * 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 declare function toJsonSchema(source: JsonSchemaSource, options?: ToJsonSchemaOptions): JSONSchema;
+/**
+ * The JSON Schema versions `fromJsonSchema()` reads: the JSON Schema drafts, or the schema objects of OpenAPI 3.0 and
+ * 3.1.
+ */
+export type JsonSchemaDialect = JsonSchemaTarget | 'draft-06';
+/**
+ * The options of the conversion of a JSON Schema into a schema
+ */
+export interface FromJsonSchemaOptions {
+    /**
+     * The version the JSON Schema is written in.
+     * @default the version its `$schema` declares, else 'draft-2020-12'
+     */
+    dialect?: JsonSchemaDialect;
+    /**
+     * The document the local references (`#/...`) are resolved in, like the OpenAPI document holding the schema
+     * object.
+     * @default the JSON Schema itself
+     */
+    document?: unknown;
+    /**
+     * Other JSON Schemas the references may refer to, by URI (their `$id`, when they have one).
+     */
+    schemas?: Record<string, unknown>;
+    /**
+     * Whether the values are converted like the schemas of lakutata do (the string `'5'` accepted as the number 5);
+     * JSON Schema does not convert.
+     * @default false
+     */
+    convert?: boolean;
+}
+/**
+ * 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 declare function fromJsonSchema(schema: JSONSchema | boolean, options?: FromJsonSchemaOptions): Schema;

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

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toJsonSchema = toJsonSchema;
+exports.fromJsonSchema = fromJsonSchema;
+const VLD_js_1 = require("./VLD.js");
+const SchemaConversionException_js_1 = require("./exceptions/SchemaConversionException.js");
+const index_js_1 = require("./engine/json-schema/index.js");
+const import_js_1 = require("./engine/json-schema/import.js");
+/**
+ * The parsers of the versions
+ */
+const parsers = {
+    'draft-2020-12': index_js_1.JsonDraft202012SchemaParser,
+    'draft-2019-09': index_js_1.JsonDraft201909SchemaParser,
+    'draft-07': index_js_1.JsonSchemaParser,
+    'draft-04': index_js_1.JsonDraft04SchemaParser,
+    'openapi-3.0': index_js_1.OpenApiSchemaParser,
+    'openapi-3.1': index_js_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)
+ * ```
+ */
+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_js_1.SchemaConversionException('Not a schema object.');
+    const target = options.target || 'draft-2020-12';
+    const Parser = parsers[target];
+    if (!Parser)
+        throw new SchemaConversionException_js_1.SchemaConversionException(`Unknown JSON Schema target: ${target}`);
+    const parser = new Parser({
+        includeSchemaDialect: !!options.dialect,
+        preferences: { ...(options.preferences || VLD_js_1.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}
+ * ```
+ */
+function fromJsonSchema(schema, options = {}) {
+    return (0, import_js_1.fromJsonSchema)(schema, options);
+}