@declaro/core 2.0.0-beta.8 → 2.0.0-y.0

package/src/schema/module.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { Module } from './module'
+import { Application } from './application'
+
+describe('Module definition', () => {
+    it('should define a module', () => {
+        const application = new Application({
+            title: 'My API',
+            version: '1.0.0',
+            description: 'My API description',
+            termsOfService: 'https://example.com/terms',
+            contact: {
+                name: 'API Support',
+                url: 'https://example.com/support',
+                email: 'test@test.com',
+            },
+        })
+
+        const module = new Module(application, {
+            name: 'Module',
+
+            description: 'Module description',
+            externalDocs: {
+                description: 'External documentation',
+                url: 'https://example.com/docs',
+            },
+        })
+
+        expect(module.application).toBeInstanceOf(Application)
+        expect(module.application.info.title).toBe('My API')
+        expect(module.application.info.version).toBe('1.0.0')
+        expect(module.application.info.description).toBe('My API description')
+
+        expect(module.tag.name).toBe('Module')
+        expect(module.tag.description).toBe('Module description')
+        expect(module.tag.externalDocs.description).toBe('External documentation')
+        expect(module.tag.externalDocs.url).toBe('https://example.com/docs')
+    })
+})

package/src/schema/module.ts

@@ -0,0 +1,6 @@
+import type { Application } from './application'
+import type { DeclaroSchema } from './types'
+
+export class Module {
+    constructor(public readonly application: Application, public readonly tag: DeclaroSchema.TagObject) {}
+}

package/src/schema/properties.ts

@@ -0,0 +1,40 @@
+import { type DeclaroSchema } from './types'
+
+export const t = {
+    string: <T extends DeclaroSchema.NonArraySchemaObject<any, any>>(property?: T) => {
+        return {
+            ...property,
+            type: 'string' as const,
+        }
+    },
+    number: <T extends DeclaroSchema.NonArraySchemaObject<any, any>>(property?: T) => {
+        return {
+            ...property,
+            type: 'number' as const,
+        }
+    },
+    boolean: <T extends DeclaroSchema.NonArraySchemaObject<any, any>>(property?: T) => {
+        return {
+            ...property,
+            type: 'boolean' as const,
+        }
+    },
+    integer: <T extends DeclaroSchema.NonArraySchemaObject<any, any>>(property?: T) => {
+        return {
+            ...property,
+            type: 'integer' as const,
+        }
+    },
+    object: <T extends DeclaroSchema.NonArraySchemaObject<any, any>>(property?: T) => {
+        return {
+            ...property,
+            type: 'object' as const,
+        }
+    },
+    array: <T extends DeclaroSchema.NonArraySchemaObject<any, any>>(property?: T) => {
+        return {
+            ...property,
+            type: 'array' as const,
+        }
+    },
+}

package/src/schema/response.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest'
+import { Response } from './response'
+import type { DeclaroSchema } from './types'
+
+describe('Response schema', () => {
+    it('should define a response schema', () => {
+        const response = new Response(200, {
+            description: 'Successful response',
+        })
+            .content('application/json', {
+                schema: {
+                    type: 'object',
+                    properties: {
+                        message: {
+                            type: 'string',
+                        },
+                    },
+                },
+            })
+            .content('application/xml', {
+                schema: {
+                    type: 'object',
+                    properties: {
+                        message: {
+                            type: 'string',
+                        },
+                    },
+                },
+            })
+            .content('application/json', {
+                schema: {
+                    type: 'object',
+                    properties: {
+                        error: {
+                            type: 'string',
+                        },
+                    },
+                },
+            })
+            .content('application/xml', {
+                schema: {
+                    type: 'object',
+                    properties: {
+                        error: {
+                            type: 'string',
+                        },
+                    },
+                },
+            })
+
+        expect(response.code).toBe(200)
+        expect(response).toBeInstanceOf(Response)
+
+        const jsonSchema = response.schema.content['application/json'].schema as DeclaroSchema.SchemaObject<any>
+        expect(jsonSchema).toBeTypeOf('object')
+        expect(jsonSchema.oneOf.length).toBe(2)
+        expect((jsonSchema.oneOf[0] as any).properties.message.type).toBe('string')
+        expect((jsonSchema.oneOf[1] as any).properties.error.type).toBe('string')
+    })
+
+    it('Should merge response schemas', () => {
+        const response = new Response(200, {
+            description: 'Successful response',
+        }).content('application/json', {
+            schema: {
+                type: 'object',
+                properties: {
+                    message: {
+                        type: 'string',
+                    },
+                },
+            },
+        })
+
+        const response2 = new Response(200, {
+            description: 'Successful response',
+        }).content('application/xml', {
+            schema: {
+                type: 'object',
+                properties: {
+                    message: {
+                        type: 'string',
+                    },
+                },
+            },
+        })
+
+        response.merge(response2)
+
+        expect(response.code).toBe(200)
+        expect(response).toBeInstanceOf(Response)
+
+        const jsonSchema = response.schema.content['application/json'].schema as DeclaroSchema.SchemaObject<any>
+        expect(jsonSchema).toBeTypeOf('object')
+        expect((jsonSchema as any).properties.message.type).toBe('string')
+
+        const xmlSchema = response.schema.content['application/xml'].schema as DeclaroSchema.SchemaObject<any>
+        expect(xmlSchema).toBeTypeOf('object')
+        expect((xmlSchema as any).properties.message.type).toBe('string')
+    })
+})

package/src/schema/response.ts

@@ -0,0 +1,93 @@
+import type { DeclaroSchema } from './types'
+import { merge, cloneDeep } from 'lodash-es'
+
+export type MediaRecord<T extends DeclaroSchema.AnyObjectProperties> = {
+    contentType: string
+    media: DeclaroSchema.MediaTypeObject<T>
+}
+
+export class Response {
+    private _code: number
+    private _response: DeclaroSchema.ResponseObject
+    private _mediaTypes: MediaRecord<any>[]
+
+    constructor(code: number, response: DeclaroSchema.ResponseObject) {
+        this._mediaTypes = []
+        const defaultDescription = code >= 200 && code < 300 ? 'Successful response' : 'Error response'
+
+        this._code = code
+        this._response = {
+            ...response,
+            description: response.description ?? defaultDescription,
+            content: {},
+        }
+    }
+
+    /**
+     *
+     * @param contentType The HTTP content type
+     * @param media The openapi media schema defining the response type.
+     * @returns An instance of the response object for chaining content types.
+     */
+    content(contentType: string, ...media: DeclaroSchema.MediaTypeObject<any>[]) {
+        this._mediaTypes.push(...media.map((m) => ({ contentType, media: m })))
+
+        return this
+    }
+
+    merge(response: Response) {
+        merge(this._response, response._response)
+        this._mediaTypes.push(...response._mediaTypes)
+
+        return this
+    }
+
+    /**
+     * The response code.
+     *
+     * Note: Read-only. This can only be initialized in the constructor.
+     */
+    get code() {
+        return this._code
+    }
+
+    /**
+     * The fully composed openapi response object.
+     */
+    get schema(): DeclaroSchema.ResponseObject {
+        const contentTypes = this.getContentTypes()
+
+        const response = cloneDeep(this._response)
+
+        contentTypes.forEach((contentType) => {
+            const media = this.getMediaForContentType(contentType)
+
+            if (media.length > 1) {
+                response.content[contentType] = {
+                    schema: {
+                        oneOf: media.map((m) => m.schema),
+                    },
+                    examples: media.reduce((acc, media) => {
+                        if (media.examples) {
+                            return { ...acc, ...media.examples }
+                        }
+
+                        return acc
+                    }, {}),
+                }
+            } else if (media.length === 1) {
+                response.content[contentType] = media[0]
+            }
+        })
+
+        return response
+    }
+
+    protected getContentTypes() {
+        return [...new Set(this._mediaTypes.map(({ contentType }) => contentType))]
+    }
+
+    protected getMediaForContentType(contentType: string) {
+        return this._mediaTypes.filter((media) => media.contentType === contentType).map((c) => c.media)
+    }
+}

package/src/schema/transform-model.ts

@@ -1,7 +1,7 @@
 import type { Model } from '.'
 import { TypescriptMap } from './supported-types'
 
-export function transformModel(model: Model) {
+export function transformModel(model: Model<any>) {
     return {
         toTypescript() {
             return [

package/src/schema/types.test.ts

@@ -0,0 +1,28 @@
+import { describe, it } from 'vitest'
+import { defineModel } from './define-model'
+import type { DeclaroSchema } from './types'
+import { t } from './properties'
+
+describe('Type tests', () => {
+    it('should infer payload types', () => {
+        const model = defineModel('Test', {
+            type: 'object',
+            properties: {
+                foo: t.string(),
+                bar: t.object({
+                    properties: {
+                        baz: t.integer(),
+                    },
+                }),
+            },
+        })
+
+        const bazModel = defineModel('Baz', {
+            properties: {
+                baz: {
+                    type: 'integer',
+                },
+            },
+        })
+    })
+})

package/src/schema/types.ts

@@ -1,30 +1,46 @@
 import type { OpenAPIV3_1 } from 'openapi-types'
 /// @ts-ignore This import is optional - it should be defined by your project's build settings (@declaro/build).
 import type { ModelNames } from '$models/reference'
+import type { EntityLabels } from './labels'
 
 export declare namespace DeclaroSchema {
+    type Modify<T, R> = Omit<T, keyof R> & R
+
     export type NonArraySchemaObjectType = OpenAPIV3_1.NonArraySchemaObjectType
     export type ArraySchemaObjectType = OpenAPIV3_1.ArraySchemaObjectType
+    export type AnySchemaObjectType = NonArraySchemaObjectType | ArraySchemaObjectType
 
-    export interface BaseSchemaObject extends OpenAPIV3_1.BaseSchemaObject {
-        $schema?: ModelNames
-        additionalProperties?: boolean | ReferenceObject | SchemaObject
-        properties?: {
-            [name: string]: ReferenceObject | SchemaObject
-        }
-        not?: ReferenceObject | SchemaObject
-        allOf?: (ReferenceObject | SchemaObject)[]
-        anyOf?: (ReferenceObject | SchemaObject)[]
-        oneOf?: (ReferenceObject | SchemaObject)[]
+    export type AnyObjectProperties = {
+        [name: string]: SchemaObject<any> | ReferenceObject
+    }
+
+    export type AnyObjectParameters = {
+        [name: string]: Omit<DeclaroSchema.ParameterObject, 'name'>
     }
 
-    export interface NonArraySchemaObject extends BaseSchemaObject {
+    export interface BaseSchemaObject<T extends AnyObjectProperties, N extends ModelNames = ModelNames>
+        extends OpenAPIV3_1.BaseSchemaObject {
+        $schema?: N
+        propertyName?: string
+        additionalProperties?: boolean | ReferenceObject | SchemaObject<T>
+        properties?: T
+        labels?: EntityLabels
+        not?: ReferenceObject | SchemaObject<T>
+        allOf?: (ReferenceObject | SchemaObject<T>)[]
+        anyOf?: (ReferenceObject | SchemaObject<T>)[]
+        oneOf?: (ReferenceObject | SchemaObject<T>)[]
+    }
+
+    export interface NonArraySchemaObject<T extends AnyObjectProperties, N extends ModelNames>
+        extends BaseSchemaObject<T, N> {
         type?: NonArraySchemaObjectType
+        labels?: EntityLabels
     }
 
-    export interface ArraySchemaObject extends BaseSchemaObject {
+    export interface ArraySchemaObject<T extends AnyObjectProperties, N extends ModelNames>
+        extends BaseSchemaObject<T> {
         type: ArraySchemaObjectType
-        items: ReferenceObject | SchemaObject
+        items: ReferenceObject | SchemaObject<T, N>
     }
 
     // Open API supports mixed schema objects, but we strategically don't yet.
@@ -34,10 +50,114 @@ export declare namespace DeclaroSchema {
     //     items?: ReferenceObject | SchemaObject
     // }
 
-    export type SchemaObject = ArraySchemaObject | NonArraySchemaObject
+    export type SchemaObject<T extends AnyObjectProperties, N extends string = string> =
+        | ArraySchemaObject<T, N>
+        | NonArraySchemaObject<T, N>
+
+    export type PropertyType<T extends SchemaObject<any>> = T['type'] extends 'string'
+        ? string
+        : T['type'] extends 'boolean'
+        ? boolean
+        : T['type'] extends 'number'
+        ? number
+        : T['type'] extends 'integer'
+        ? number
+        : T['type'] extends 'object'
+        ? ObjectPayload<T['properties']>
+        : T['type'] extends 'array'
+        ? ObjectPayload<T['properties']>[]
+        : any
+
+    export type OperationInput<T extends AnyObjectParameters> = {
+        [K in keyof T]: PropertyType<T[K]['schema']>
+    }
+
+    export type ObjectPayload<T extends AnyObjectProperties> = {
+        [K in keyof T]: PropertyType<T[K]>
+    }
+
+    export type Payload<T extends AnyObjectProperties, TSchema extends SchemaObject<T>> = any
 
     export interface ReferenceObject {
         $ref: ModelNames
-        format: string
+        format?: string
     }
+
+    export type InfoObject = OpenAPIV3_1.InfoObject
+
+    export type TagObject = OpenAPIV3_1.TagObject
+
+    export type ExampleObject = OpenAPIV3_1.ExampleObject
+    export type MediaTypeObject<T extends AnyObjectProperties> = Modify<
+        OpenAPIV3_1.MediaTypeObject,
+        {
+            schema?: SchemaObject<T> | ReferenceObject
+            examples?: Record<string, ReferenceObject | ExampleObject>
+        }
+    >
+    export type ServerObject = OpenAPIV3_1.ServerObject
+    export type LinkObject = Modify<
+        OpenAPIV3_1.LinkObject,
+        {
+            server?: ServerObject
+        }
+    >
+
+    export type ResponseObject = Modify<
+        OpenAPIV3_1.ResponseObject,
+        {
+            headers?: {
+                [header: string]: ReferenceObject | HeaderObject
+            }
+            content?: {
+                [media: string]: MediaTypeObject<any>
+            }
+            links?: {
+                [link: string]: ReferenceObject | LinkObject
+            }
+        }
+    >
+    export type ResponsesObject = OpenAPIV3_1.ResponsesObject
+
+    export type HeaderObject = OpenAPIV3_1.HeaderObject
+    export type HttpMethods = OpenAPIV3_1.HttpMethods
+
+    // export type ParameterObject = OpenAPIV3_1.ParameterObject
+    export type ParameterObject = Modify<
+        OpenAPIV3_1.ParameterObject,
+        {
+            in: 'query' | 'header' | 'path' | 'cookie'
+            schema?: SchemaObject<any> | ReferenceObject
+        }
+    >
+
+    export type RequestBodyObject<T extends AnyObjectProperties> = Modify<
+        OpenAPIV3_1.RequestBodyObject,
+        {
+            content: {
+                [media: string]: MediaTypeObject<T>
+            }
+        }
+    >
+    export type CallbackObject = Record<string, PathItemObject | ReferenceObject>
+    export type PathItemObject<T extends {} = {}> = Modify<
+        OpenAPIV3_1.PathItemObject<T>,
+        {
+            servers?: ServerObject[]
+            parameters?: (ReferenceObject | ParameterObject)[]
+        }
+    > & {
+        [method in HttpMethods]?: OperationObject<T>
+    }
+    export type OperationObject<T extends {} = {}> = Modify<
+        OpenAPIV3_1.OperationObject<T>,
+        {
+            parameters?: ParameterObject[]
+            requestBody?: ReferenceObject | RequestBodyObject<T>
+            responses?: ResponsesObject
+            callbacks?: Record<string, ReferenceObject | CallbackObject>
+            servers?: ServerObject[]
+        }
+    > &
+        T
 }