@tstdl/base 0.91.52 → 0.92.0

package/ai/data-extracting.d.ts

@@ -1 +1,36 @@
 import '../polyfills.js';
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { type FileMetadataResponse, GoogleAIFileManager } from '@google/generative-ai/server';
+import { Resolvable, type resolveArgumentType } from '../injector/interfaces.js';
+import { SchemaTestable } from '../schema/index.js';
+import { Enumeration as EnumerationType, EnumerationValue } from '../types.js';
+import { LiteralUnion } from 'type-fest';
+export type FileInput = {
+    path: string;
+    mimeType: string;
+} | Blob;
+export type GenerativeAIModel = LiteralUnion<'gemini-2.0-flash-exp' | 'gemini-exp-1206' | 'gemini-2.0-flash-thinking-exp-1219', string>;
+export type AiServiceOptions = {
+    apiKey: string;
+    model?: GenerativeAIModel;
+};
+export type AiServiceArgument = AiServiceOptions;
+export declare class AiService implements Resolvable<AiServiceArgument> {
+    #private;
+    readonly genAI: GoogleGenerativeAI;
+    readonly fileManager: GoogleAIFileManager;
+    readonly model: import("@google/generative-ai").GenerativeModel;
+    readonly [resolveArgumentType]: AiServiceArgument;
+    getFile(fileInput: FileInput): Promise<FileMetadataResponse>;
+    getFiles(files: FileInput[]): Promise<FileMetadataResponse[]>;
+    classify<T extends EnumerationType>(fileInput: FileInput, types: T): Promise<{
+        reasoning: string;
+        types: {
+            type: EnumerationValue<T>;
+            confidence: 'high' | 'medium' | 'low';
+        }[] | null;
+    }>;
+    extractData<T>(fileInput: FileInput, schema: SchemaTestable<T>): Promise<T>;
+    waitForFileActive(fileMetadata: FileMetadataResponse): Promise<FileMetadataResponse>;
+    waitForFilesActive(...files: FileMetadataResponse[]): Promise<FileMetadataResponse[]>;
+}

package/ai/data-extracting.js

@@ -4,59 +4,213 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
 import '../polyfills.js';
+import { openAsBlob } from 'node:fs';
+import { unlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { GoogleGenerativeAI } from '@google/generative-ai';
 import { FileState, GoogleAIFileManager } from '@google/generative-ai/server';
-import { Application } from '../application/application.js';
 import { DetailsError } from '../errors/details.error.js';
 import { Singleton } from '../injector/decorators.js';
-import { inject } from '../injector/inject.js';
+import { injectArgument } from '../injector/inject.js';
+import { convertToOpenApiSchema } from '../schema/converters/openapi-converter.js';
+import { array, enumeration, nullable, object, Schema, string } from '../schema/index.js';
+import { digest } from '../utils/cryptography.js';
 import { timeout } from '../utils/timing.js';
-const generationConfig = {
-    temperature: 1,
-    topP: 0.95,
-    topK: 40,
-    maxOutputTokens: 8192,
-    responseMimeType: 'text/plain',
-};
+import { tryIgnoreAsync } from '../utils/try-ignore.js';
+import { isBlob } from '../utils/type-guards.js';
+import { millisecondsPerSecond } from '../utils/units.js';
 let AiService = class AiService {
-    apiKey = 'AIzaSyDAFOSnn3it7EUIWNTp86kPb1os8P3nyu0';
-    genAI = new GoogleGenerativeAI(this.apiKey);
-    fileManager = new GoogleAIFileManager(this.apiKey);
-    model = this.genAI.getGenerativeModel({ model: 'gemini-2.0-flash-thinking-exp-1219' });
-    async classify(_path) {
-    }
-    async extractData(path) {
-        const { file } = await this.fileManager.uploadFile(path, { mimeType: 'application/pdf' });
-        await this.waitForFilesActive(file);
-        const chatSession = this.model.startChat({ generationConfig });
-        const result = await chatSession.sendMessageStream([
-            { fileData: { mimeType: file.mimeType, fileUri: file.uri } },
-            { text: 'extract data as json' }
-        ]);
-        for await (const part of result.stream) {
-            process.stdout.write(part.text());
-        }
-        console.log((await result.response).usageMetadata);
-    }
-    async waitForFilesActive(...files) {
-        for (const name of files.map((file) => file.name)) {
-            let file = await this.fileManager.getFile(name);
-            while (file.state == FileState.PROCESSING) {
-                await timeout(2500);
-                file = await this.fileManager.getFile(name);
+    #options = injectArgument(this);
+    #fileCache = new Map();
+    genAI = new GoogleGenerativeAI(this.#options.apiKey);
+    fileManager = new GoogleAIFileManager(this.#options.apiKey);
+    model = this.genAI.getGenerativeModel({ model: this.#options.model ?? 'gemini-2.0-flash-exp' });
+    async getFile(fileInput) {
+        const path = isBlob(fileInput) ? join(tmpdir(), crypto.randomUUID()) : fileInput.path;
+        const mimeType = isBlob(fileInput) ? fileInput.type : fileInput.mimeType;
+        const blob = isBlob(fileInput) ? fileInput : await openAsBlob(path, { type: mimeType });
+        const buffer = await blob.arrayBuffer();
+        const byteArray = new Uint8Array(buffer);
+        const fileHash = await digest('SHA-256', byteArray).toBase64();
+        const fileKey = `${fileHash}:${byteArray.length}`;
+        if (this.#fileCache.has(fileKey)) {
+            try {
+                const cachedFile = await this.#fileCache.get(fileKey);
+                return await this.fileManager.getFile(cachedFile.name);
             }
-            if (file.state == FileState.FAILED) {
-                throw new DetailsError(file.error?.message ?? `Failed to process file ${file.name}`, file.error?.details);
+            catch {
+                this.#fileCache.delete(fileKey);
             }
         }
+        const filePromise = (async () => {
+            try {
+                const env_1 = { stack: [], error: void 0, hasError: false };
+                try {
+                    const stack = __addDisposableResource(env_1, new AsyncDisposableStack(), true);
+                    if (isBlob(fileInput)) {
+                        stack.defer(async () => tryIgnoreAsync(async () => unlink(path)));
+                        await writeFile(path, byteArray);
+                    }
+                    const result = await this.fileManager.uploadFile(path, { mimeType });
+                    return await this.waitForFileActive(result.file);
+                }
+                catch (e_1) {
+                    env_1.error = e_1;
+                    env_1.hasError = true;
+                }
+                finally {
+                    const result_1 = __disposeResources(env_1);
+                    if (result_1)
+                        await result_1;
+                }
+            }
+            catch (error) {
+                this.#fileCache.delete(fileKey);
+                throw error;
+            }
+        })();
+        this.#fileCache.set(fileKey, filePromise);
+        return filePromise;
+    }
+    async getFiles(files) {
+        return Promise.all(files.map(async (file) => this.getFile(file)));
+    }
+    async classify(fileInput, types) {
+        const file = await this.getFile(fileInput);
+        const resultSchema = object({
+            reasoning: string({ description: 'Reasoning for classification. Use to be more confident, if unsure. Reason for every somewhat likely document type.' }),
+            types: nullable(array(object({
+                type: enumeration(types, { description: 'Type of document' }),
+                confidence: enumeration(['high', 'medium', 'low'], { description: 'How sure/certain you are about the classficiation.' })
+            }), { description: 'One or more document types that matches' }))
+        });
+        const responseSchema = convertToOpenApiSchema(resultSchema);
+        const result = await this.model.generateContent({
+            generationConfig: {
+                maxOutputTokens: 1024,
+                temperature: 0.5,
+                responseMimeType: 'application/json',
+                responseSchema
+            },
+            systemInstruction: 'You are a highly accurate document classification AI. Your task is to analyze the content of a given document and determine its type based on a predefined list of possible document types.',
+            contents: [
+                {
+                    role: 'user',
+                    parts: [
+                        { fileData: { mimeType: file.mimeType, fileUri: file.uri } },
+                        { text: `Classify the document. Output as JSON using the following schema:\n${JSON.stringify(responseSchema, null, 2)}\n\nIf none of the provided document types are a suitable match, return null for types.` }
+                    ]
+                }
+            ]
+        });
+        return resultSchema.parse(JSON.parse(result.response.text()));
+    }
+    async extractData(fileInput, schema) {
+        const file = await this.getFile(fileInput);
+        const responseSchema = convertToOpenApiSchema(schema);
+        const result = await this.model.generateContent({
+            generationConfig: {
+                maxOutputTokens: 4096,
+                temperature: 0.5,
+                responseMimeType: 'application/json',
+                responseSchema
+            },
+            systemInstruction: `You are a highly skilled data extraction AI, specializing in accurately identifying and extracting information from unstructured text documents and converting it into a structured JSON format. Your primary goal is to meticulously follow the provided JSON schema and populate it with data extracted from the given document.
+
+**Instructions:**
+Carefully read and analyze the provided document. Identify relevant information that corresponds to each field in the JSON schema. Focus on accuracy and avoid making assumptions. If a field has multiple possible values, extract all relevant ones into the correct array structures ONLY IF the schema defines that field as an array; otherwise, extract only the single most relevant value.
+
+**Reasoning**
+Reason about every field in the json schema and find the best matching value. If there are multiple relevant values but the data type is not an array, reason about the values to find out which is the most relevant one.
+
+You *MUST* output the reasoning first.`,
+            contents: [
+                {
+                    role: 'user',
+                    parts: [
+                        { fileData: { mimeType: file.mimeType, fileUri: file.uri } },
+                        { text: `Classify the document. Output as JSON using the following schema:\n${JSON.stringify(responseSchema, null, 2)}` }
+                    ]
+                }
+            ]
+        });
+        return Schema.parse(schema, JSON.parse(result.response.text()));
+    }
+    async waitForFileActive(fileMetadata) {
+        let file = await this.fileManager.getFile(fileMetadata.name);
+        while (file.state == FileState.PROCESSING) {
+            await timeout(millisecondsPerSecond);
+            file = await this.fileManager.getFile(fileMetadata.name);
+        }
+        if (file.state == FileState.FAILED) {
+            throw new DetailsError(file.error?.message ?? `Failed to process file ${file.name}`, file.error?.details);
+        }
+        return file;
+    }
+    async waitForFilesActive(...files) {
+        const responses = [];
+        for (const file of files) {
+            const respones = await this.waitForFileActive(file);
+            responses.push(respones);
+        }
+        return responses;
     }
 };
 AiService = __decorate([
     Singleton()
 ], AiService);
-async function main() {
-    const aiService = inject(AiService);
-    await aiService.extractData('/home/patrick/Downloads/358 417/orig/358 417.pdf');
-}
-Application.run(main);
+export { AiService };

package/file/mime-type.d.ts

@@ -1,2 +1,2 @@
-export declare function getMimeType(file: Uint8Array | ReadableStream<Uint8Array>): Promise<string>;
+export declare function getMimeType(file: string | Uint8Array | ReadableStream<Uint8Array>): Promise<string>;
 export declare function getMimeTypeExtensions(mimeType: string): string[];

package/file/mime-type.js

@@ -1,10 +1,12 @@
 import { dynamicImport } from '../import.js';
 import { decodeTextStream } from '../utils/encoding.js';
 import { readTextStream } from '../utils/stream/stream-reader.js';
-import { isUint8Array } from '../utils/type-guards.js';
+import { isReadableStream, isString, isUint8Array } from '../utils/type-guards.js';
 import { mimeTypesMap } from './mime-types.js';
 export async function getMimeType(file) {
-    return spawnFileCommand(['--brief', '--mime-type', '-'], file);
+    const path = isString(file) ? file : '-';
+    const data = isString(file) ? undefined : file;
+    return spawnFileCommand(['--brief', '--mime-type', path], data);
 }
 export function getMimeTypeExtensions(mimeType) {
     return mimeTypesMap.get(mimeType) ?? [];
@@ -15,7 +17,10 @@ async function spawnFileCommand(args, file) {
     const process = spawn('file', args, { stdio: 'pipe' });
     const stdin = Writable.toWeb(process.stdin);
     const stdout = Readable.toWeb(process.stdout).pipeThrough(decodeTextStream());
-    if (isUint8Array(file)) {
+    if (isReadableStream(file)) {
+        await file.pipeTo(stdin);
+    }
+    else if (isUint8Array(file)) {
         const writer = stdin.getWriter();
         try {
             await writer.write(file);
@@ -23,9 +28,6 @@ async function spawnFileCommand(args, file) {
         }
         catch { /* File command closes stream as soon as it has the required data */ }
     }
-    else {
-        await file.pipeTo(stdin);
-    }
     const output = await readTextStream(stdout);
     return output.trim();
 }

package/file/mime-types.js

@@ -51,14 +51,7 @@ export const mimeTypes = {
     'application/mp4': ['mp4s'],
     'application/msword': ['doc', 'dot'],
     'application/mxf': ['mxf'],
-    'application/octet-stream': [
-        'bin', 'dms',
-        'lrf', 'mar',
-        'so', 'dist',
-        'distz', 'pkg',
-        'bpk', 'dump',
-        'elc', 'deploy'
-    ],
+    'application/octet-stream': ['bin', 'dms', 'lrf', 'mar', 'so', 'dist', 'distz', 'pkg', 'bpk', 'dump', 'elc', 'deploy'],
     'application/oda': ['oda'],
     'application/oebps-package+xml': ['opf'],
     'application/ogg': ['ogx'],
@@ -499,13 +492,7 @@ export const mimeTypes = {
     'application/x-csh': ['csh'],
     'application/x-debian-package': ['deb', 'udeb'],
     'application/x-dgc-compressed': ['dgc'],
-    'application/x-director': [
-        'dir', 'dcr',
-        'dxr', 'cst',
-        'cct', 'cxt',
-        'w3d', 'fgd',
-        'swa'
-    ],
+    'application/x-director': ['dir', 'dcr', 'dxr', 'cst', 'cct', 'cxt', 'w3d', 'fgd', 'swa'],
     'application/x-doom': ['wad'],
     'application/x-dtbncx+xml': ['ncx'],
     'application/x-dtbook+xml': ['dtb'],
@@ -583,11 +570,7 @@ export const mimeTypes = {
     'application/x-xliff+xml': ['xlf'],
     'application/x-xpinstall': ['xpi'],
     'application/x-xz': ['xz'],
-    'application/x-zmachine': [
-        'z1', 'z2', 'z3',
-        'z4', 'z5', 'z6',
-        'z7', 'z8'
-    ],
+    'application/x-zmachine': ['z1', 'z2', 'z3', 'z4', 'z5', 'z6', 'z7', 'z8'],
     'application/xaml+xml': ['xaml'],
     'application/xcap-diff+xml': ['xdf'],
     'application/xenc+xml': ['xenc'],
@@ -710,12 +693,7 @@ export const mimeTypes = {
     'text/html': ['html', 'htm'],
     'text/javascript': ['js', 'mjs'],
     'text/n3': ['n3'],
-    'text/plain': [
-        'txt', 'text',
-        'conf', 'def',
-        'list', 'log',
-        'in'
-    ],
+    'text/plain': ['txt', 'text', 'conf', 'def', 'list', 'log', 'in'],
     'text/prs.lines.tag': ['dsc'],
     'text/richtext': ['rtx'],
     'text/sgml': ['sgml', 'sgm'],
@@ -738,12 +716,7 @@ export const mimeTypes = {
     'text/vnd.wap.wml': ['wml'],
     'text/vnd.wap.wmlscript': ['wmls'],
     'text/x-asm': ['s', 'asm'],
-    'text/x-c': [
-        'c', 'cc',
-        'cxx', 'cpp',
-        'h', 'hh',
-        'dic'
-    ],
+    'text/x-c': ['c', 'cc', 'cxx', 'cpp', 'h', 'hh', 'dic'],
     'text/x-fortran': ['f', 'for', 'f77', 'f90'],
     'text/x-java-source': ['java'],
     'text/x-nfo': ['nfo'],

package/orm/schemas/numeric-date.d.ts

@@ -1,5 +1,5 @@
 import { NumberSchema, type NumberSchemaOptions, type SchemaPropertyDecorator, type SchemaPropertyDecoratorOptions, type SimpleSchemaOptions } from '../../schema/index.js';
-export type NumericDateSchemaOptions = SimpleSchemaOptions & Pick<NumberSchemaOptions, 'minimum' | 'maximum'>;
+export type NumericDateSchemaOptions = SimpleSchemaOptions<number> & Pick<NumberSchemaOptions, 'minimum' | 'maximum'>;
 export declare class NumericDateSchema extends NumberSchema {
     readonly name = "NumericDate";
     constructor(options?: NumericDateSchemaOptions);

package/orm/schemas/timestamp.d.ts

@@ -1,6 +1,6 @@
 import type { JsonPath } from '../../json-path/json-path.js';
 import { NumberSchema, type NumberSchemaOptions, type SchemaPropertyDecorator, type SchemaPropertyDecoratorOptions, type SchemaTestOptions, type SchemaTestResult, type SimpleSchemaOptions } from '../../schema/index.js';
-export type TimestampSchemaOptions = SimpleSchemaOptions & Pick<NumberSchemaOptions, 'minimum' | 'maximum'>;
+export type TimestampSchemaOptions = SimpleSchemaOptions<number> & Pick<NumberSchemaOptions, 'minimum' | 'maximum'>;
 export declare class TimestampSchema extends NumberSchema {
     readonly name = "Timestamp";
     constructor(options?: TimestampSchemaOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tstdl/base",
-  "version": "0.91.52",
+  "version": "0.92.0",
   "author": "Patrick Hein",
   "publishConfig": {
     "access": "public"

package/schema/converters/index.d.ts

@@ -0,0 +1 @@
+export * from './openapi-converter.js';

package/schema/converters/index.js

@@ -0,0 +1 @@
+export * from './openapi-converter.js';

package/schema/converters/openapi-converter.d.ts

@@ -0,0 +1,3 @@
+import type { UndefinableJsonObject } from '../../types.js';
+import type { SchemaTestable } from '../schema.js';
+export declare function convertToOpenApiSchema(testable: SchemaTestable): UndefinableJsonObject;

package/schema/converters/openapi-converter.js

@@ -0,0 +1,113 @@
+import { NotSupportedError } from '../../errors/not-supported.error.js';
+import { fromEntries, objectEntries } from '../../utils/object/object.js';
+import { isDefined, isNotNull, isNumber, isString } from '../../utils/type-guards.js';
+import { ArraySchema } from '../schemas/array.js';
+import { BooleanSchema } from '../schemas/boolean.js';
+import { DateSchema } from '../schemas/date.js';
+import { EnumerationSchema } from '../schemas/enumeration.js';
+import { LiteralSchema } from '../schemas/literal.js';
+import { nullable, NullableSchema } from '../schemas/nullable.js';
+import { NumberSchema } from '../schemas/number.js';
+import { ObjectSchema } from '../schemas/object.js';
+import { OptionalSchema } from '../schemas/optional.js';
+import { StringSchema } from '../schemas/string.js';
+import { UnionSchema } from '../schemas/union.js';
+import { schemaTestableToSchema } from '../testable.js';
+export function convertToOpenApiSchema(testable) {
+    const schema = schemaTestableToSchema(testable);
+    return {
+        ...convertToOpenApiSchemaBase(schema),
+        ...(isNotNull(schema.description) ? { description: schema.description } : undefined),
+        ...(isDefined(schema.example) ? { example: schema.example } : undefined)
+    };
+}
+function convertToOpenApiSchemaBase(schema) {
+    if (schema instanceof ObjectSchema) {
+        const entries = objectEntries(schema.properties);
+        const convertedEntries = entries.map(([property, propertySchema]) => [property, convertToOpenApiSchema(stripOptional(propertySchema))]);
+        return {
+            type: 'object',
+            properties: fromEntries(convertedEntries),
+            required: entries
+                .filter(([, propertySchema]) => !(propertySchema instanceof OptionalSchema) && !((propertySchema instanceof NullableSchema) && (propertySchema.schema instanceof OptionalSchema)))
+                .map(([property]) => property)
+        };
+    }
+    if (schema instanceof StringSchema) {
+        return {
+            type: 'string'
+        };
+    }
+    if (schema instanceof DateSchema) {
+        return {
+            type: 'string',
+            format: 'date-time'
+        };
+    }
+    if (schema instanceof NumberSchema) {
+        return {
+            type: schema.integer ? 'integer' : 'number',
+            ...(isNumber(schema.minimum) ? { minimum: schema.minimum } : undefined),
+            ...(isNumber(schema.maximum) ? { maximum: schema.maximum } : undefined)
+        };
+    }
+    if (schema instanceof BooleanSchema) {
+        return {
+            type: 'boolean'
+        };
+    }
+    if (schema instanceof LiteralSchema) {
+        return {
+            type: typeof schema.value,
+            enum: [schema.value]
+        };
+    }
+    if (schema instanceof ArraySchema) {
+        return {
+            type: 'array',
+            items: convertToOpenApiSchema(schema.itemSchema),
+            ...(isNumber(schema.minimum) ? { minItems: schema.minimum } : undefined),
+            ...(isNumber(schema.maximum) ? { maxItems: schema.maximum } : undefined)
+        };
+    }
+    if (schema instanceof EnumerationSchema) {
+        const hasString = schema.allowedValues.some(isString);
+        const hasNumber = schema.allowedValues.some(isNumber);
+        if (hasString && hasNumber) {
+            throw new NotSupportedError('Enum must be either string or number but not both.');
+        }
+        return {
+            type: hasString ? 'string' : 'number',
+            enum: schema.allowedValues
+        };
+    }
+    if (schema instanceof NullableSchema) {
+        if (schema.schema instanceof EnumerationSchema) {
+            const enumSchema = convertToOpenApiSchema(schema.schema);
+            return {
+                ...enumSchema,
+                enum: [...enumSchema.enum, null],
+                nullable: true
+            };
+        }
+        return {
+            ...convertToOpenApiSchema(schema.schema),
+            nullable: true
+        };
+    }
+    if (schema instanceof UnionSchema) {
+        return {
+            oneOf: schema.schemas.map((innerSchema) => convertToOpenApiSchema(innerSchema))
+        };
+    }
+    throw new NotSupportedError(`Schema "${schema.name}" not supported.`);
+}
+function stripOptional(schema) {
+    if ((schema instanceof OptionalSchema)) {
+        return schema.schema;
+    }
+    if ((schema instanceof NullableSchema) && (schema.schema instanceof OptionalSchema)) {
+        return nullable(schema.schema.schema);
+    }
+    return schema;
+}

package/schema/decorators/description.d.ts

@@ -0,0 +1,3 @@
+import { type Decorator } from '../../reflection/index.js';
+import type { SchemaTypeReflectionData } from './types.js';
+export declare function Description(options?: SchemaTypeReflectionData): Decorator<'class' | 'property'>;

package/schema/decorators/description.js

@@ -0,0 +1,10 @@
+/* eslint-disable @typescript-eslint/naming-convention */
+import { createDecorator } from '../../reflection/index.js';
+export function Description(options = {}) {
+    return createDecorator({
+        class: true,
+        property: true,
+        data: { schema: options },
+        mergeData: true
+    });
+}

package/schema/decorators/property.d.ts

@@ -2,9 +2,11 @@ import type { SetRequired } from 'type-fest';
 import type { Decorator } from '../../reflection/index.js';
 import type { TypedOmit } from '../../types.js';
 import type { SchemaTestable } from '../schema.js';
-import type { SchemaPropertyReflectionData } from './types.js';
+import type { SchemaPropertyReflectionData, SchemaTestableProvider } from './types.js';
 export type SchemaPropertyDecoratorOptions = SchemaPropertyReflectionData;
 export type SchemaPropertyDecoratorOptionsWithRequiredSchema = SetRequired<SchemaPropertyReflectionData, 'schema'>;
 export type SchemaPropertyDecoratorOptionsWithoutSchema = TypedOmit<SchemaPropertyReflectionData, 'schema'>;
 export declare function Property(schema: SchemaTestable, options?: SchemaPropertyDecoratorOptionsWithoutSchema): Decorator<'property' | 'accessor'>;
 export declare function Property(options: SchemaPropertyDecoratorOptionsWithRequiredSchema): Decorator<'property' | 'accessor'>;
+export declare function PropertySchema(schemaProvider: SchemaTestableProvider, options?: SchemaPropertyDecoratorOptionsWithoutSchema): Decorator<'property' | 'accessor'>;
+export declare function PropertySchema(options: SchemaPropertyDecoratorOptionsWithRequiredSchema): Decorator<'property' | 'accessor'>;

package/schema/decorators/property.js

@@ -1,13 +1,21 @@
 /* eslint-disable @typescript-eslint/naming-convention */
-import { isDefined } from '../../utils/type-guards.js';
-import { isSchemaTestable } from '../testable.js';
+import { isDefined, isFunction } from '../../utils/type-guards.js';
 import { createSchemaPropertyDecorator } from './utils.js';
 export function Property(schemaOrOptions, optionsOrNothing) {
     if (isDefined(optionsOrNothing)) {
-        return createSchemaPropertyDecorator({ ...optionsOrNothing, schema: schemaOrOptions });
+        return createSchemaPropertyDecorator({ ...optionsOrNothing, schema: () => schemaOrOptions });
     }
-    if (isSchemaTestable(schemaOrOptions)) {
-        return createSchemaPropertyDecorator({ schema: schemaOrOptions });
+    if (isFunction(schemaOrOptions)) {
+        return createSchemaPropertyDecorator({ schema: () => schemaOrOptions });
     }
     return createSchemaPropertyDecorator(schemaOrOptions);
 }
+export function PropertySchema(schemaProviderOrOptions, optionsOrNothing) {
+    if (isDefined(optionsOrNothing)) {
+        return createSchemaPropertyDecorator({ ...optionsOrNothing, schema: schemaProviderOrOptions });
+    }
+    if (isFunction(schemaProviderOrOptions)) {
+        return createSchemaPropertyDecorator({ schema: schemaProviderOrOptions });
+    }
+    return createSchemaPropertyDecorator(schemaProviderOrOptions);
+}

package/schema/decorators/types.d.ts

@@ -1,16 +1,16 @@
 import type { Decorator } from '../../reflection/types.js';
-import type { SchemaTestable } from '../schema.js';
+import type { SchemaOptions, SchemaTestable } from '../schema.js';
 import type { ObjectSchemaFactory, ObjectSchemaOptions } from '../schemas/object.js';
 export type SchemaClassDecorator = Decorator<'class'>;
 export type SchemaPropertyDecorator = Decorator<'property' | 'accessor'>;
-export type SchemaTypeReflectionData = Partial<Pick<ObjectSchemaOptions, 'mask' | 'unknownProperties' | 'unknownPropertiesKey'>> & {
+export type SchemaTypeReflectionData = Partial<Pick<ObjectSchemaOptions, 'mask' | 'unknownProperties' | 'unknownPropertiesKey' | 'description' | 'example'>> & {
     schema?: SchemaTestable;
     factory?: ObjectSchemaFactory<any>;
 };
-export type SchemaPropertyReflectionData = {
-    schema?: SchemaTestable;
+export type SchemaTestableProvider = (data: SchemaPropertyReflectionData) => SchemaTestable;
+export type SchemaPropertyReflectionData = Partial<Pick<SchemaOptions<any>, 'description' | 'example'>> & {
+    schema?: SchemaTestableProvider;
     array?: boolean;
     optional?: boolean;
     nullable?: boolean;
-    data?: Record<PropertyKey, any>;
 };