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

package/src/schema/application.test.ts

@@ -0,0 +1,286 @@
+import { describe, expect, it } from 'vitest'
+import { Application } from './application'
+import { Module } from './module'
+import { defineModel } from './define-model'
+import type { OpenAPIV3_1 } from 'openapi-types'
+import { Response } from './response'
+
+describe('Application schema', () => {
+    it('should define an application schema', () => {
+        const app = 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',
+            },
+        })
+
+        expect(app.info.title).toBe('My API')
+        expect(app.info.version).toBe('1.0.0')
+        expect(app.info.description).toBe('My API description')
+        expect(app.info.termsOfService).toBe('https://example.com/terms')
+        expect(app.info.contact.name).toBe('API Support')
+        expect(app.info.contact.url).toBe('https://example.com/support')
+        expect(app.info.contact.email).toBe('test@test.com')
+    })
+
+    it('should be able to add a module', () => {
+        const app = 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 result = app.defineModule({
+            name: 'Module',
+            description: 'Module description',
+            externalDocs: {
+                description: 'External documentation',
+                url: 'https://example.com/docs',
+            },
+        })
+
+        expect(result).toBeInstanceOf(Module)
+
+        const module = app.getModule('Module')
+
+        expect(module).toBeInstanceOf(Module)
+
+        expect(module.application).toBeInstanceOf(Application)
+        expect(module.application.info.title).toBe('My API')
+        expect(module.application.info.version).toBe('1.0.0')
+
+        expect(module).toBeInstanceOf(Module)
+        expect(module.tag.name).toBe('Module')
+        expect(module.tag.description).toBe('Module description')
+        expect(module.tag.externalDocs.description).toBe('External documentation')
+    })
+
+    it('Should allow multiple module definitions to be chained', () => {
+        const app = 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',
+            },
+        })
+
+        app.defineModule({
+            name: 'Module1',
+            description: 'Module 1 description',
+            externalDocs: {
+                description: 'External documentation 1',
+                url: 'https://example.com/docs1',
+            },
+        })
+        app.defineModule({
+            name: 'Module2',
+            description: 'Module 2 description',
+            externalDocs: {
+                description: 'External documentation 2',
+                url: 'https://example.com/docs2',
+            },
+        })
+
+        const module1 = app.getModule('Module1')
+        const module2 = app.getModule('Module2')
+
+        expect(module1.tag.name).toBe('Module1')
+        expect(module1.tag.description).toBe('Module 1 description')
+        expect(module1.tag.externalDocs.description).toBe('External documentation 1')
+        expect(module1.tag.externalDocs.url).toBe('https://example.com/docs1')
+
+        expect(module2.tag.name).toBe('Module2')
+        expect(module2.tag.description).toBe('Module 2 description')
+        expect(module2.tag.externalDocs.description).toBe('External documentation 2')
+        expect(module2.tag.externalDocs.url).toBe('https://example.com/docs2')
+    })
+
+    it('Should allow models to be added to the application', () => {
+        const app = 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 model1 = defineModel('Model1', {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                },
+            },
+        })
+
+        const model2 = defineModel('Model2', {
+            type: 'object',
+            properties: {
+                number: {
+                    type: 'integer',
+                },
+            },
+        })
+
+        app.addModel(model1, model2)
+
+        const allModels = app.getModels()
+
+        expect(allModels).toHaveLength(2)
+
+        expect(allModels[0].name).toBe('Model1')
+        expect(allModels[1].name).toBe('Model2')
+    })
+
+    it('Should allow responses to be added to the application', () => {
+        const app = 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 error500 = new Response(500, {
+            description: 'Internal server error',
+        }).content('application/json', {
+            schema: {
+                type: 'object',
+                properties: {
+                    message: {
+                        type: 'string',
+                    },
+                },
+            },
+        })
+
+        const error404 = new Response(404, {
+            description: 'Not found',
+        }).content('application/json', {
+            schema: {
+                type: 'object',
+                properties: {
+                    message: {
+                        type: 'string',
+                    },
+                },
+            },
+        })
+
+        const error400 = new Response(400, {
+            description: 'Bad request',
+        }).content('application/json', {
+            schema: {
+                type: 'object',
+                properties: {
+                    message: {
+                        type: 'string',
+                    },
+                },
+            },
+        })
+
+        app.addResponse(error500, error404, error400)
+
+        const response500 = app.getResponse(500)
+        const response404 = app.getResponse(404)
+        const response400 = app.getResponse(400)
+
+        const allResponses = app.getResponseSchema()
+
+        expect(response500.code).toBe(500)
+        expect(response500.schema.description).toBe('Internal server error')
+
+        expect(response404.code).toBe(404)
+        expect(response404.schema.description).toBe('Not found')
+
+        expect(response400.code).toBe(400)
+        expect(response400.schema.description).toBe('Bad request')
+
+        expect(allResponses[500].description).toBe('Internal server error')
+        expect((allResponses[500] as any).content['application/json'].schema.type).toBe('object')
+        expect((allResponses[500] as any).content['application/json'].schema.properties.message.type).toBe('string')
+
+        expect(allResponses[404].description).toBe('Not found')
+        expect((allResponses[404] as any).content['application/json'].schema.type).toBe('object')
+        expect((allResponses[404] as any).content['application/json'].schema.properties.message.type).toBe('string')
+
+        expect(allResponses[400].description).toBe('Bad request')
+        expect((allResponses[400] as any).content['application/json'].schema.type).toBe('object')
+        expect((allResponses[400] as any).content['application/json'].schema.properties.message.type).toBe('string')
+    })
+
+    it('Should allow paths to be added to the application', () => {
+        function test(doc: OpenAPIV3_1.Document) {}
+
+        test({
+            openapi: '3.0.0',
+            info: {
+                title: 'My API',
+                version: '1.0.0',
+            },
+            paths: {
+                '/test': {
+                    get: {
+                        description: 'Test endpoint',
+                        responses: {
+                            200: {
+                                description: 'Successful response',
+                                content: {
+                                    'application/json': {
+                                        schema: {
+                                            oneOf: [
+                                                {
+                                                    type: 'object',
+                                                    properties: {
+                                                        message: {
+                                                            type: 'string',
+                                                        },
+                                                    },
+                                                },
+                                                {
+                                                    type: 'object',
+                                                    properties: {
+                                                        error: {
+                                                            type: 'string',
+                                                        },
+                                                    },
+                                                },
+                                            ],
+                                        },
+                                    },
+                                },
+                            },
+                            500: {
+                                description: 'Internal server error',
+                            },
+                        },
+                    },
+                },
+            },
+        })
+    })
+})

package/src/schema/application.ts

@@ -0,0 +1,150 @@
+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,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { defineModel } from '.'
+import { defineModel, type ModelName, type ModelProperties } from '.'
+import { t } from './properties'
 
 describe('Model definition', async () => {
     it('should define a model', async () => {
@@ -8,6 +9,10 @@ describe('Model definition', async () => {
             properties: {
                 title: {
                     type: 'string',
+                    labels: {
+                        singularEntityName: 'Title',
+                        pluralEntityName: 'Titles',
+                    },
                 },
                 year: {
                     type: 'integer',
@@ -15,21 +20,62 @@ describe('Model definition', async () => {
                 },
             },
             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.schema).toEqual({
+        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,19 +1,50 @@
-import { OpenAPIV3, type OpenAPIV3_1 } from 'openapi-types'
 import type { DeclaroSchema } from './types'
 
-export type Model = {
-    name: string
-    schema: DeclaroSchema.SchemaObject
+export type Model<
+    T extends DeclaroSchema.AnyObjectProperties = DeclaroSchema.AnyObjectProperties,
+    N extends Readonly<string> = string,
+> = {
+    name: N
+    schema: DeclaroSchema.SchemaObject<T>
     isModel: true
 }
 
-export function defineModel(
+type TraverseSchemaFn<T extends DeclaroSchema.AnyObjectProperties> = (
     name: string,
-    doc: DeclaroSchema.SchemaObject,
-): Model {
+    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,
-        schema: doc,
+        name: name as Readonly<N>,
+        schema: { ...doc },
         isModel: true,
     }
 }

package/src/schema/index.ts

@@ -1,3 +1,10 @@
 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

@@ -0,0 +1,60 @@
+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/labels.ts

@@ -0,0 +1,30 @@
+import { capitalCase, camelCase, paramCase, pascalCase } from 'change-case'
+import pluralize from 'pluralize'
+
+export type EntityLabels = {
+    singularLabel?: string
+    pluralLabel?: string
+    singularParameter?: string
+    pluralParameter?: string
+    singularSlug?: string
+    pluralSlug?: string
+    singularEntityName?: string
+    pluralEntityName?: string
+    singularTableName?: string
+    pluralTableName?: string
+}
+
+export function getEntityLabels(entity: string, labels: Partial<EntityLabels> = {}): EntityLabels {
+    return {
+        singularLabel: labels.singularLabel ?? capitalCase(pluralize(entity, 1)),
+        pluralLabel: labels.pluralLabel ?? capitalCase(pluralize(entity, 10)),
+        singularParameter: labels.singularParameter ?? camelCase(pluralize(entity, 1)),
+        pluralParameter: labels.pluralParameter ?? camelCase(pluralize(entity, 10)),
+        singularSlug: labels.singularSlug ?? paramCase(pluralize(entity, 1)),
+        pluralSlug: labels.pluralSlug ?? paramCase(pluralize(entity, 10)),
+        singularEntityName: labels.singularEntityName ?? pascalCase(pluralize(entity, 1)),
+        pluralEntityName: labels.pluralEntityName ?? pascalCase(pluralize(entity, 10)),
+        singularTableName: labels.singularTableName ?? paramCase(pluralize(entity, 1)),
+        pluralTableName: labels.pluralTableName ?? paramCase(pluralize(entity, 10)),
+    }
+}