@declaro/core 2.0.0-y.0 → 2.1.0

package/src/schema/application.ts

@@ -1,150 +0,0 @@
-import { cloneDeep } from 'lodash-es'
-import type { Model } from './define-model'
-import { Module } from './module'
-import type { DeclaroSchema } from './types'
-import { Response } from './response'
-
-export type ModuleFactory = (mod: Module) => Module | undefined
-
-export class Application {
-    private _info: DeclaroSchema.InfoObject
-    private _modules: Map<string, Module>
-    private _models: Map<string, Model>
-    private _responses: Map<number, Response>
-
-    constructor(info: DeclaroSchema.InfoObject) {
-        this._info = info
-        this._modules = new Map()
-        this._models = new Map()
-        this._responses = new Map()
-    }
-
-    /**
-     * Get the application info (read-only). Application info can only be set in the constructor of the application.
-     *
-     * Note: This should be set by the application implementation. It would be dangerous for any one module to be able to change the application info for all of the others.
-     */
-    get info() {
-        return cloneDeep(this._info)
-    }
-
-    /**
-     * Define a module for the application.
-     *
-     * @param tag The tag info for the module, to be used in the OpenAPI schema
-     * @param factory A convenience function to define the module, adding endpoints, etc.
-     * @returns
-     */
-    defineModule(tag: DeclaroSchema.TagObject, factory?: ModuleFactory) {
-        let mod = new Module(this, tag)
-        const result = factory?.(mod)
-
-        if (result instanceof Module) {
-            mod = result
-        } else if (!!result) {
-            throw new Error('Module factory must return a Module instance or undefined')
-        }
-
-        this._modules.set(tag.name, mod)
-
-        return mod
-    }
-
-    /**
-     * Get a module by name.
-     *
-     * @param name The name of the module to get
-     * @returns The `Module` instance for the given name
-     */
-    getModule(name: string): Module {
-        return this._modules.get(name)
-    }
-
-    /**
-     * Add models to the application.
-     *
-     * @param models The models to add to the application
-     * @example app.addModel(User)
-     * @example app.addModel(User, Post)
-     * @example app.addModel(...myModels)
-     * @returns The application instance
-     */
-    addModel(...models: Model[]) {
-        models.forEach((model) => {
-            this._models.set(model.name, model)
-        })
-
-        return this
-    }
-
-    /**
-     * Get a model by name.
-     *
-     * @param name The name of the model to get
-     * @returns The `Model` instance for the given name
-     */
-    getModel(name: string): Model {
-        return this._models.get(name)
-    }
-
-    /**
-     * Get all models.
-     *
-     * @returns All models in the application
-     */
-    getModels(): Model[] {
-        return Array.from(this._models.values())
-    }
-
-    /**
-     * Add a response to the application.
-     *
-     * @param code The HTTP status code for the response
-     * @param response The response object
-     * @returns The application instance
-     */
-    addResponse(...responses: Response[]) {
-        responses.forEach((response) => {
-            const existingResponse = this.getResponse(response.code)
-
-            if (existingResponse) {
-                existingResponse.merge(response)
-            } else {
-                this._responses.set(response.code, response)
-            }
-        })
-        return this
-    }
-
-    /**
-     * Get a response by status code.
-     *
-     * @param code The HTTP status code for the response
-     * @returns The `Response` instance for the given status code
-     */
-    getResponse(code: number): Response {
-        return this._responses.get(code)
-    }
-
-    /**
-     * Get all responses. (read-only)
-     *
-     * @returns All responses in the application
-     */
-    get responses(): Map<number, Response> {
-        return new Map(this._responses)
-    }
-
-    /**
-     * Get all responses as a hash of keys and values.
-     *
-     * @returns A hash of keys and values representing all responses in the application
-     */
-    getResponseSchema(): DeclaroSchema.ResponsesObject {
-        const responsesHash: { [key: string]: DeclaroSchema.ResponseObject } = {}
-        this._responses.forEach((value, key) => {
-            responsesHash[key] = value.schema
-        })
-        return responsesHash
-    }
-}

package/src/schema/define-model.test.ts

@@ -1,81 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { defineModel, type ModelName, type ModelProperties } from '.'
-import { t } from './properties'
-
-describe('Model definition', async () => {
-    it('should define a model', async () => {
-        const movie = defineModel('Movie', {
-            type: 'object',
-            properties: {
-                title: {
-                    type: 'string',
-                    labels: {
-                        singularEntityName: 'Title',
-                        pluralEntityName: 'Titles',
-                    },
-                },
-                year: {
-                    type: 'integer',
-                    format: 'int32',
-                },
-            },
-            required: ['title'],
-            labels: {
-                singularEntityName: 'Movie',
-                pluralEntityName: 'Movies',
-            },
-        })
-
-        const name: ModelName<typeof movie> = movie.name
-        const properties: ModelProperties<typeof movie> = movie.schema.properties
-
-        expect(name).toBe('Movie')
-        expect(properties.title.type).toBe('string')
-
-        expect(movie.name).toBe('Movie')
-        expect(movie.isModel).toBe(true)
-        expect(movie.schema.type).toBe('object')
-        expect(movie.schema.properties.title['type']).toBe('string')
-        expect(movie.schema.properties.year['type']).toBe('integer')
-        expect(movie.schema.properties.year['format']).toBe('int32')
-        expect(movie.schema.required).toEqual(['title'])
-        expect(movie.schema.labels).toBeTypeOf('object')
-        expect(movie.schema.labels.pluralEntityName).toBe('Movies')
-        expect(movie.schema.labels.singularEntityName).toBe('Movie')
-
-        expect(movie.schema.properties.title.labels).toBeTypeOf('object')
-        expect(movie.schema.properties.title.labels.pluralEntityName).toBe('Titles')
-        expect(movie.schema.properties.title.labels.singularEntityName).toBe('Title')
-        expect((movie.schema.properties.title.labels as any).pluralSlug).toBe(undefined) // Only include explicitly defined labels—leave the rest up to the framework
-    })
-
-    it('should define a model with nested properties', async () => {
-        const movie = defineModel('Movie', {
-            type: 'object',
-            properties: {
-                title: {
-                    type: 'string',
-                    labels: {
-                        singularEntityName: 'Title',
-                        pluralEntityName: 'Titles',
-                    },
-                },
-                year: {
-                    type: 'integer',
-                    format: 'int32',
-                },
-                meta: {
-                    type: 'object',
-                    properties: {
-                        rating: t.integer(),
-                    },
-                },
-            },
-            required: ['title'],
-            labels: {
-                singularEntityName: 'Movie',
-                pluralEntityName: 'Movies',
-            },
-        })
-    })
-})

package/src/schema/define-model.ts

@@ -1,50 +0,0 @@
-import type { DeclaroSchema } from './types'
-
-export type Model<
-    T extends DeclaroSchema.AnyObjectProperties = DeclaroSchema.AnyObjectProperties,
-    N extends Readonly<string> = string,
-> = {
-    name: N
-    schema: DeclaroSchema.SchemaObject<T>
-    isModel: true
-}
-
-type TraverseSchemaFn<T extends DeclaroSchema.AnyObjectProperties> = (
-    name: string,
-    property: DeclaroSchema.SchemaObject<any>,
-    schema: DeclaroSchema.SchemaObject<T>,
-) => DeclaroSchema.SchemaObject<any>
-
-export type ModelName<T extends Model<any, string>> = T['name']
-export type ModelProperties<T extends Model<any, string>> = T['schema']['properties']
-
-function traverseSchema<T extends DeclaroSchema.AnyObjectProperties>(
-    schema: DeclaroSchema.SchemaObject<T>,
-    fn: TraverseSchemaFn<T>,
-) {
-    for (const [key, value] of Object.entries(schema.properties ?? {})) {
-        let properties: DeclaroSchema.AnyObjectProperties = schema.properties!
-        properties[key] = fn(key, value, schema)
-    }
-}
-
-export function initializeModel(schema: DeclaroSchema.SchemaObject<any>) {
-    return schema
-}
-
-export function defineModel<T extends DeclaroSchema.AnyObjectProperties, N extends Readonly<string>>(
-    name: N,
-    doc: DeclaroSchema.SchemaObject<T>,
-): Model<T, N> {
-    traverseSchema(doc, (name, property, schema) => {
-        return initializeModel({
-            propertyName: name,
-            ...property,
-        })
-    })
-    return {
-        name: name as Readonly<N>,
-        schema: { ...doc },
-        isModel: true,
-    }
-}

package/src/schema/formats.ts

@@ -1,23 +0,0 @@
-export enum RelationFormat {
-    OneToOne = 'one-to-one',
-    OneToMany = 'one-to-many',
-    ManyToOne = 'many-to-one',
-    ManyToMany = 'many-to-many',
-    EmbeddedObject = 'embedded-object',
-    EmbeddedArray = 'embedded-array',
-}
-
-export type RelationReferenceType = 'object' | 'array'
-
-export function getReferenceType(format: string): RelationReferenceType {
-    switch (format) {
-        case RelationFormat.OneToOne:
-        case RelationFormat.ManyToOne:
-        case RelationFormat.EmbeddedObject:
-            return 'object'
-        case RelationFormat.OneToMany:
-        case RelationFormat.ManyToMany:
-        case RelationFormat.EmbeddedArray:
-            return 'array'
-    }
-}

package/src/schema/index.ts

@@ -1,10 +0,0 @@
-export * from './define-model'
-export * from './supported-types'
-export * from './transform-model'
-export * from './labels'
-export * from './module'
-export * from './application'
-export * from './response'
-export * from './formats'
-export * from './properties'
-export * from './types'

package/src/schema/labels.test.ts

@@ -1,60 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { getEntityLabels } from './labels'
-
-describe('Entity Labels', () => {
-    it('Should be able to define labels for entities', () => {
-        const labels = getEntityLabels('User')
-
-        expect(labels.singularLabel).toBe('User')
-        expect(labels.pluralLabel).toBe('Users')
-        expect(labels.singularParameter).toBe('user')
-        expect(labels.pluralParameter).toBe('users')
-        expect(labels.singularSlug).toBe('user')
-        expect(labels.pluralSlug).toBe('users')
-        expect(labels.singularEntityName).toBe('User')
-        expect(labels.pluralEntityName).toBe('Users')
-        expect(labels.singularTableName).toBe('user')
-        expect(labels.pluralTableName).toBe('users')
-    })
-
-    it('Should handle different types of entity names', () => {
-        const twoWords = getEntityLabels('SomeEntity')
-
-        expect(twoWords.singularLabel).toBe('Some Entity')
-        expect(twoWords.pluralLabel).toBe('Some Entities')
-        expect(twoWords.singularParameter).toBe('someEntity')
-        expect(twoWords.pluralParameter).toBe('someEntities')
-        expect(twoWords.singularSlug).toBe('some-entity')
-        expect(twoWords.pluralSlug).toBe('some-entities')
-        expect(twoWords.singularEntityName).toBe('SomeEntity')
-        expect(twoWords.pluralEntityName).toBe('SomeEntities')
-        expect(twoWords.singularTableName).toBe('some-entity')
-        expect(twoWords.pluralTableName).toBe('some-entities')
-
-        const threeWords = getEntityLabels('SomeOtherEntity')
-
-        expect(threeWords.singularLabel).toBe('Some Other Entity')
-        expect(threeWords.pluralLabel).toBe('Some Other Entities')
-        expect(threeWords.singularParameter).toBe('someOtherEntity')
-        expect(threeWords.pluralParameter).toBe('someOtherEntities')
-        expect(threeWords.singularSlug).toBe('some-other-entity')
-        expect(threeWords.pluralSlug).toBe('some-other-entities')
-        expect(threeWords.singularEntityName).toBe('SomeOtherEntity')
-        expect(threeWords.pluralEntityName).toBe('SomeOtherEntities')
-        expect(threeWords.singularTableName).toBe('some-other-entity')
-        expect(threeWords.pluralTableName).toBe('some-other-entities')
-
-        const sentence = getEntityLabels('Some other entity')
-
-        expect(sentence.singularLabel).toBe('Some Other Entity')
-        expect(sentence.pluralLabel).toBe('Some Other Entities')
-        expect(sentence.singularParameter).toBe('someOtherEntity')
-        expect(sentence.pluralParameter).toBe('someOtherEntities')
-        expect(sentence.singularSlug).toBe('some-other-entity')
-        expect(sentence.pluralSlug).toBe('some-other-entities')
-        expect(sentence.singularEntityName).toBe('SomeOtherEntity')
-        expect(sentence.pluralEntityName).toBe('SomeOtherEntities')
-        expect(sentence.singularTableName).toBe('some-other-entity')
-        expect(sentence.pluralTableName).toBe('some-other-entities')
-    })
-})

package/src/schema/module.test.ts

@@ -1,39 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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

@@ -1,101 +0,0 @@
-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

@@ -1,93 +0,0 @@
-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/supported-types.test.ts

@@ -1,20 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { TypescriptMap } from './supported-types'
-
-describe('Supported types', async () => {
-    it('should support scalar types', async () => {
-        expect(TypescriptMap.string).toBe('string')
-        expect(TypescriptMap.text).toBe('string')
-
-        expect(TypescriptMap.integer).toBe('number')
-        expect(TypescriptMap.number).toBe('number')
-        expect(TypescriptMap.float).toBe('number')
-        expect(TypescriptMap.double).toBe('number')
-
-        expect(TypescriptMap.boolean).toBe('boolean')
-
-        expect(TypescriptMap.date).toBe('Date')
-        expect(TypescriptMap.datetime).toBe('Date')
-        expect(TypescriptMap.time).toBe('Date')
-    })
-})