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

package/dist/schema/application.d.ts

@@ -0,0 +1,83 @@
+import { Model } from './define-model';
+import { Module } from './module';
+import { DeclaroSchema } from './types';
+import { Response } from './response';
+export type ModuleFactory = (mod: Module) => Module | undefined;
+export declare class Application {
+    private _info;
+    private _modules;
+    private _models;
+    private _responses;
+    constructor(info: DeclaroSchema.InfoObject);
+    /**
+     * 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(): import("openapi-types").OpenAPIV3_1.InfoObject;
+    /**
+     * 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): Module;
+    /**
+     * 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;
+    /**
+     * 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[]): 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;
+    /**
+     * Get all models.
+     *
+     * @returns All models in the application
+     */
+    getModels(): Model[];
+    /**
+     * 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[]): 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;
+    /**
+     * Get all responses. (read-only)
+     *
+     * @returns All responses in the application
+     */
+    get responses(): Map<number, Response>;
+    /**
+     * 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;
+}

package/dist/schema/application.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schema/define-model.d.ts

@@ -1,7 +1,10 @@
 import { 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 declare function defineModel(name: string, doc: DeclaroSchema.SchemaObject): Model;
+export type ModelName<T extends Model<any, string>> = T['name'];
+export type ModelProperties<T extends Model<any, string>> = T['schema']['properties'];
+export declare function initializeModel(schema: DeclaroSchema.SchemaObject<any>): DeclaroSchema.SchemaObject<any, string>;
+export declare function defineModel<T extends DeclaroSchema.AnyObjectProperties, N extends Readonly<string>>(name: N, doc: DeclaroSchema.SchemaObject<T>): Model<T, N>;

package/dist/schema/index.d.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/dist/schema/labels.d.ts

@@ -0,0 +1,13 @@
+export type EntityLabels = {
+    singularLabel?: string;
+    pluralLabel?: string;
+    singularParameter?: string;
+    pluralParameter?: string;
+    singularSlug?: string;
+    pluralSlug?: string;
+    singularEntityName?: string;
+    pluralEntityName?: string;
+    singularTableName?: string;
+    pluralTableName?: string;
+};
+export declare function getEntityLabels(entity: string, labels?: Partial<EntityLabels>): EntityLabels;

package/dist/schema/labels.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schema/module.d.ts

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

package/dist/schema/module.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schema/properties.d.ts

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

package/dist/schema/response.d.ts

@@ -0,0 +1,31 @@
+import { DeclaroSchema } from './types';
+export type MediaRecord<T extends DeclaroSchema.AnyObjectProperties> = {
+    contentType: string;
+    media: DeclaroSchema.MediaTypeObject<T>;
+};
+export declare class Response {
+    private _code;
+    private _response;
+    private _mediaTypes;
+    constructor(code: number, response: DeclaroSchema.ResponseObject);
+    /**
+     *
+     * @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;
+    merge(response: Response): this;
+    /**
+     * The response code.
+     *
+     * Note: Read-only. This can only be initialized in the constructor.
+     */
+    get code(): number;
+    /**
+     * The fully composed openapi response object.
+     */
+    get schema(): DeclaroSchema.ResponseObject;
+    protected getContentTypes(): string[];
+    protected getMediaForContentType(contentType: string): DeclaroSchema.MediaTypeObject<any>[];
+}

package/dist/schema/response.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/schema/transform-model.d.ts

@@ -1,4 +1,4 @@
 import { Model } from '.';
-export declare function transformModel(model: Model): {
+export declare function transformModel(model: Model<any>): {
     toTypescript(): string;
 };

package/dist/schema/types.d.ts

@@ -1,29 +1,95 @@
 import { OpenAPIV3_1 } from 'openapi-types';
 import { ModelNames } from '$models/reference';
+import { EntityLabels } from './labels';
 export declare namespace DeclaroSchema {
+    type Modify<T, R> = Omit<T, keyof R> & R;
     type NonArraySchemaObjectType = OpenAPIV3_1.NonArraySchemaObjectType;
     type ArraySchemaObjectType = OpenAPIV3_1.ArraySchemaObjectType;
-    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)[];
+    type AnySchemaObjectType = NonArraySchemaObjectType | ArraySchemaObjectType;
+    type AnyObjectProperties = {
+        [name: string]: SchemaObject<any> | ReferenceObject;
+    };
+    type AnyObjectParameters = {
+        [name: string]: Omit<DeclaroSchema.ParameterObject, 'name'>;
+    };
+    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>)[];
     }
-    interface NonArraySchemaObject extends BaseSchemaObject {
+    interface NonArraySchemaObject<T extends AnyObjectProperties, N extends ModelNames> extends BaseSchemaObject<T, N> {
         type?: NonArraySchemaObjectType;
+        labels?: EntityLabels;
     }
-    interface ArraySchemaObject extends BaseSchemaObject {
+    interface ArraySchemaObject<T extends AnyObjectProperties, N extends ModelNames> extends BaseSchemaObject<T> {
         type: ArraySchemaObjectType;
-        items: ReferenceObject | SchemaObject;
+        items: ReferenceObject | SchemaObject<T, N>;
     }
-    type SchemaObject = ArraySchemaObject | NonArraySchemaObject;
+    type SchemaObject<T extends AnyObjectProperties, N extends string = string> = ArraySchemaObject<T, N> | NonArraySchemaObject<T, N>;
+    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;
+    type OperationInput<T extends AnyObjectParameters> = {
+        [K in keyof T]: PropertyType<T[K]['schema']>;
+    };
+    type ObjectPayload<T extends AnyObjectProperties> = {
+        [K in keyof T]: PropertyType<T[K]>;
+    };
+    type Payload<T extends AnyObjectProperties, TSchema extends SchemaObject<T>> = any;
     interface ReferenceObject {
         $ref: ModelNames;
-        format: string;
+        format?: string;
     }
+    type InfoObject = OpenAPIV3_1.InfoObject;
+    type TagObject = OpenAPIV3_1.TagObject;
+    type ExampleObject = OpenAPIV3_1.ExampleObject;
+    type MediaTypeObject<T extends AnyObjectProperties> = Modify<OpenAPIV3_1.MediaTypeObject, {
+        schema?: SchemaObject<T> | ReferenceObject;
+        examples?: Record<string, ReferenceObject | ExampleObject>;
+    }>;
+    type ServerObject = OpenAPIV3_1.ServerObject;
+    type LinkObject = Modify<OpenAPIV3_1.LinkObject, {
+        server?: ServerObject;
+    }>;
+    type ResponseObject = Modify<OpenAPIV3_1.ResponseObject, {
+        headers?: {
+            [header: string]: ReferenceObject | HeaderObject;
+        };
+        content?: {
+            [media: string]: MediaTypeObject<any>;
+        };
+        links?: {
+            [link: string]: ReferenceObject | LinkObject;
+        };
+    }>;
+    type ResponsesObject = OpenAPIV3_1.ResponsesObject;
+    type HeaderObject = OpenAPIV3_1.HeaderObject;
+    type HttpMethods = OpenAPIV3_1.HttpMethods;
+    type ParameterObject = Modify<OpenAPIV3_1.ParameterObject, {
+        in: 'query' | 'header' | 'path' | 'cookie';
+        schema?: SchemaObject<any> | ReferenceObject;
+    }>;
+    type RequestBodyObject<T extends AnyObjectProperties> = Modify<OpenAPIV3_1.RequestBodyObject, {
+        content: {
+            [media: string]: MediaTypeObject<T>;
+        };
+    }>;
+    type CallbackObject = Record<string, PathItemObject | ReferenceObject>;
+    type PathItemObject<T extends {} = {}> = Modify<OpenAPIV3_1.PathItemObject<T>, {
+        servers?: ServerObject[];
+        parameters?: (ReferenceObject | ParameterObject)[];
+    }> & {
+        [method in HttpMethods]?: OperationObject<T>;
+    };
+    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;
 }

package/dist/schema/types.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/typescript/constant-manipulation/snake-case.d.ts

@@ -0,0 +1,22 @@
+/**
+ * This util converts typescript constants to snake case.
+ *
+ * Why would anyone do this to themselves? Because now we can take constants defined in one place in one case (i.e. a data type called "User") and we can automatically infer strongly typed dirivative types (i.e. snake case table name) without needing to generate code.
+ *
+ * Limitations:
+ * - This utility is designed to work with typescript constants, not arbitrary strings.
+ * - This utility supports only the English alphabet, numerals, and a few special characters (-_ ).
+ *
+ * Note: This was built with the help of AI (Github Copilot). See adjacent md file for info.
+ *
+ */
+type LowercaseLetters = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
+type Numerals = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type UppercaseLetters = Uppercase<LowercaseLetters>;
+type AllowedSpecialCharacters = ' ' | '_' | '-';
+type Replace<S extends string, From extends string, To extends string> = S extends '' ? '' : S extends `${infer P}${From}${infer R}` ? `${P}${To}${Replace<R, From, To>}` : S;
+type Trim<S extends string> = S extends `${AllowedSpecialCharacters}${infer T}` ? Trim<T> : S extends `${infer T}${AllowedSpecialCharacters}` ? Trim<T> : S;
+type CamelToSnakeCase<S extends string, Acc extends string = ''> = S extends `${infer L}${infer R}` ? L extends LowercaseLetters ? `${Acc}${L}` extends `${infer T}${UppercaseLetters}` | `${infer T}${Numerals}` ? CamelToSnakeCase<R, `${T}_${Lowercase<L>}`> : CamelToSnakeCase<R, `${Acc}${L}`> : L extends UppercaseLetters ? CamelToSnakeCase<R, `${Acc}_${Lowercase<L>}`> : L extends Numerals ? `${Acc}` extends `${infer T}${LowercaseLetters}` ? CamelToSnakeCase<R, `${Acc}_${L}`> : `${Acc}${L}` extends `${infer T}${Numerals}` ? CamelToSnakeCase<R, `${T}${L}`> : CamelToSnakeCase<R, `${Acc}_${L}`> : CamelToSnakeCase<R, Acc> : Acc;
+type Normalize<S extends string> = Lowercase<Trim<Replace<Replace<Replace<S, ' ', '_'>, '-', '_'>, '__', '_'>>>;
+export type SnakeCase<S extends string> = Normalize<CamelToSnakeCase<S>>;
+export {};

package/dist/typescript/index.d.ts

@@ -5,3 +5,4 @@ export * from './classes';
 export * from './fetch';
 export * from './promises';
 export * from './baseModel';
+export * from './constant-manipulation/snake-case';

package/dist/typescript/objects.d.ts

@@ -4,3 +4,9 @@ export default _default;
 export type DeepPartial<T> = T extends object ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
+/**
+ * Merge two object types without using an intersection type. Intersection types preserve the original types of the objects causing confusion, while this type will merge the types of the objects.
+ */
+export type Merge<A, B> = {
+    [key in keyof A | keyof B]: key extends keyof B ? B[key] : key extends keyof A ? A[key] : never;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@declaro/core",
-    "version": "2.0.0-beta.9",
+    "version": "2.0.0-y.0",
     "description": "Declarative Business Module Definition",
     "main": "dist/pkg.cjs",
     "module": "dist/pkg.mjs",
@@ -18,13 +18,18 @@
         "test": "vitest"
     },
     "devDependencies": {
+        "@types/whatwg-url": "^13.0.0",
         "@vitest/coverage-v8": "^2.0.5",
         "json-schema-library": "^7.4.8",
+        "lodash": "^4.17.21",
+        "minimatch": "^10.0.1",
+        "node-mocks-http": "^1.16.2",
         "openapi-types": "^12.1.3",
         "typescript": "^5.5.4",
         "vite": "^5.4.1",
         "vite-plugin-dts": "^4.0.3",
-        "vitest": "^2.0.5"
+        "vitest": "^2.0.5",
+        "whatwg-url": "^14.1.1"
     },
     "dependencies": {
         "change-case": "^4.1.2",
@@ -38,5 +43,5 @@
         "url": "https://github.com/emmertio/declaro/issues"
     },
     "homepage": "https://github.com/emmertio/declaro/tree/main#readme",
-    "gitHead": "f5a767905883063873fa1b6d4c592bf2c9bb8235"
+    "gitHead": "639b567b4f8adfb9da9c3005c3b0ac0aca10c0e6"
 }

package/src/app/app-context.ts

@@ -0,0 +1,14 @@
+import { useHeader } from '../http/headers'
+import { Context } from '../context/context'
+
+/**
+ * Get the name of the app making the current request via header x-app. (returns "default" when no app was provided).
+ *
+ * @param context
+ * @returns the name of the app in a string.
+ */
+export function useApp(context: Context) {
+    const appHeader = useHeader(context, 'x-app') as string
+
+    return appHeader ?? 'default'
+}

package/src/app/app-lifecycle.ts

@@ -0,0 +1,14 @@
+import { Context, type ContextListener } from '../context/context'
+import { App } from './app'
+
+export function onInit(context: Context, listener: ContextListener) {
+    context.on(App.Events.Init, listener)
+}
+
+export function onStart(context: Context, listener: ContextListener) {
+    context.on(App.Events.Start, listener)
+}
+
+export function onDestroy(context: Context, listener: ContextListener) {
+    context.on(App.Events.Destroy, listener)
+}

package/src/app/app.ts

@@ -0,0 +1,45 @@
+import { Context, type ContextMiddleware, type ContextListener } from '../context/context'
+import { onDestroy, onInit, onStart } from './app-lifecycle'
+
+export type AppConfig = {
+    context?: Context
+    init?: ContextMiddleware
+    start?: ContextMiddleware
+    destroy?: ContextMiddleware
+}
+
+export class App {
+    constructor(public readonly context: Context) {}
+
+    static Events = {
+        Init: 'declaro:init',
+        Start: 'declaro:start',
+        Destroy: 'declaro:destroy',
+    }
+
+    async init() {
+        await this.context.emit(App.Events.Init)
+    }
+
+    onInit(listener: ContextListener) {
+        onInit(this.context, listener)
+        return this
+    }
+
+    async start() {
+        await this.context.emit(App.Events.Start)
+    }
+
+    onStart(listener: ContextListener) {
+        onStart(this.context, listener)
+        return
+    }
+
+    async destroy() {
+        await this.context.emit(App.Events.Start)
+    }
+
+    onDestroy(listener: ContextListener) {
+        onDestroy(this.context, listener)
+    }
+}

package/src/app/index.ts

@@ -1,34 +1,3 @@
-import { type ContextMiddleware } from '../context'
-
-export type AppMeta = {
-    /**
-     * A human-friendly title for your app
-     */
-    title: string
-    /**
-     * A unique parameterized name for your app
-     */
-    name: string
-    /**
-     * A human-friendly description for your app
-     */
-    description: string
-    /**
-     * A URL to a logo for your app
-     */
-}
-
-export type App = {
-    meta: AppMeta
-    context: ContextMiddleware
-}
-
-export function defineApp(
-    meta: AppMeta,
-    configureContext: ContextMiddleware,
-): App {
-    return {
-        meta,
-        context: configureContext,
-    }
-}
+export * from './app-context'
+export * from './app-lifecycle'
+export * from './app'