@declaro/core 2.0.0-beta.9 → 2.0.0-beta.90

package/src/http/request.spec.ts

@@ -0,0 +1,52 @@
+import { Context } from '../context/context'
+import { createRequest } from 'node-mocks-http'
+import { provideRequest, useRequest, useRequestMethod } from './request'
+import { describe, expect, it } from 'vitest'
+
+describe('Http Request', () => {
+    it('Should get undefined by default', () => {
+        const context = new Context()
+
+        const request = useRequest(context)
+
+        expect(request).toBeUndefined()
+    })
+    it('Should provide a request', () => {
+        const context = new Context()
+
+        const request = createRequest({
+            method: 'GET',
+            url: '/test',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Test': 'test',
+                Authorization: 'Bearer 123',
+            },
+        })
+
+        provideRequest(context, request)
+
+        const request2 = useRequest(context)
+
+        expect(request2).toEqual(request)
+    })
+
+    it('Should get the method', () => {
+        const context = new Context()
+
+        const request = createRequest({
+            method: 'GET',
+            url: '/test',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-Test': 'test',
+            },
+        })
+
+        provideRequest(context, request)
+
+        const method = useRequestMethod(context)
+
+        expect(method).toEqual('GET')
+    })
+})

package/src/http/request.ts

@@ -0,0 +1,43 @@
+import type { IncomingMessage } from 'http'
+import { Context, type DeclaroRequestScope } from '../context/context'
+
+export interface Request extends IncomingMessage {}
+
+/**
+ * Provide a request to a context that supports request scope.
+ * The context must have all properties required by DeclaroRequestScope.
+ *
+ * @param context A context that includes DeclaroRequestScope properties
+ * @param request The request to provide
+ */
+export function provideRequest<S extends DeclaroRequestScope>(context: Context<S>, request: Request) {
+    context.registerValue('request', request)
+}
+
+/**
+ * Get the request from the context.
+ *
+ * @deprecated You can now inject the request directly from Context<RequestScope>.
+ * This function will be removed in a future version.
+ * @param context The context to use for the request.
+ * @returns
+ */
+export function useRequest(context: Context) {
+    const request = context.resolve('request')
+
+    return request
+}
+
+/**
+ * Get the HTTP method of the request.
+ *
+ * @deprecated You can now inject the request directly from Context<RequestScope>.
+ * This function will be removed in a future version.
+ * @param context The context to use for the request.
+ * @returns The HTTP method of the request, or undefined if not available.
+ */
+export function useRequestMethod(context: Context) {
+    const request = useRequest(context)
+
+    return request?.method
+}

package/src/http/url.spec.ts

@@ -0,0 +1,87 @@
+// Tests for url.ts:
+// Create tests for the following functions:
+// - useURL: make sure it returns undefined by default, and the URL object if provided
+// - provideURL: make sure you can provide a URL object or a string
+// - useURLString: make sure it returns the stringified URL
+// - useURLDomain: make sure it returns the domain part of the URL provided
+// - useURLPath
+
+import { Context } from '../context/context'
+import { useRequestDomain, useRequestPath, useRequestQuery, useRequestURL, useRequestURLString } from './url'
+import { provideRequest } from './request'
+import { createRequest } from 'node-mocks-http'
+import { describe, expect, it } from 'vitest'
+
+// - useURLQueryString
+describe('Http URL', () => {
+    const testUrlString = 'https://example.com/test?a=1&b=2'
+    const testUrlObject = new URL(testUrlString)
+    const request = createRequest({
+        method: 'GET',
+        url: testUrlString,
+        headers: {
+            'Content-Type': 'application/json',
+            'X-Test': 'test',
+            Authorization: 'Bearer 123',
+        },
+    })
+
+    it('Should get undefined by default', () => {
+        const context = new Context()
+
+        const url = useRequestURL(context)
+
+        expect(url).toBeUndefined()
+    })
+
+    it('Should get the URL object if provided', () => {
+        const context = new Context()
+
+        provideRequest(context, request)
+
+        const url2 = useRequestURL(context)
+
+        expect(url2).toEqual(testUrlObject)
+    })
+
+    it('Should get the stringified URL', () => {
+        const context = new Context()
+
+        provideRequest(context, request)
+
+        const url2 = useRequestURLString(context)
+
+        expect(url2).toEqual(testUrlString)
+    })
+
+    it('Should get the domain part of the URL', () => {
+        const context = new Context()
+
+        provideRequest(context, request)
+
+        const domain = useRequestDomain(context)
+
+        expect(domain).toEqual('example.com')
+    })
+
+    it('Should get the path part of the URL', () => {
+        const context = new Context()
+
+        provideRequest(context, request)
+
+        const path = useRequestPath(context)
+
+        expect(path).toEqual('/test')
+    })
+
+    it('Should get the query string part of the URL', () => {
+        const context = new Context()
+
+        provideRequest(context, request)
+
+        const query = useRequestQuery(context)
+
+        expect(query['a']).toEqual('1')
+        expect(query['b']).toEqual('2')
+    })
+})

package/src/http/url.ts

@@ -0,0 +1,48 @@
+import { Context } from '../context/context'
+import { URL } from 'whatwg-url'
+import { useRequest } from './request'
+
+export function useRequestURL(context: Context): URL | undefined {
+    const request = useRequest(context)
+    const url = request?.url && new URL(request?.url)
+
+    return url as URL
+}
+
+export function useRequestURLString(context: Context) {
+    const url = useRequestURL(context)
+
+    return url?.toString()
+}
+
+export function useRequestDomain(context: Context) {
+    const url = useRequestURL(context)
+
+    return url?.hostname
+}
+
+export function useRequestPath(context: Context) {
+    const url = useRequestURL(context)
+
+    return url?.pathname
+}
+
+export function useRequestQuery(context: Context): Record<string, string> {
+    const url = useRequestURL(context)
+
+    const qs = url?.searchParams
+
+    // convert qs to an object of key value pairs
+    const qsMap = [...(qs?.entries() as any)].reduce((qsMap, [key, value]) => {
+        qsMap[key] = value
+        return qsMap
+    }, {} as Record<string, string>)
+
+    return qsMap
+}
+
+export function useFormattedQueryParam(context: Context, key: string) {
+    const qs = useRequestQuery(context)
+
+    const value = qs[key]
+}

package/src/index.ts

@@ -1,13 +1,48 @@
+export type {
+    /**
+     * @deprecated Import AppScope from '#scope' instead.
+     *
+     * Migration: Change `import { AppScope } from '@declaro/core'` to `import { AppScope } from '#scope'`
+     *
+     * The #scope import allows for better type augmentation and module resolution.
+     */
+    AppScope,
+    /**
+     * @deprecated Import RequestScope from '#scope' instead.
+     *
+     * Migration: Change `import { RequestScope } from '@declaro/core'` to `import { RequestScope } from '#scope'`
+     *
+     * The #scope import allows for better type augmentation and module resolution.
+     */
+    RequestScope,
+} from '#scope'
+
+export * from '@standard-schema/spec'
+
 export * from './typescript'
 export * from './app'
-export * from './server'
-export * from './context'
+export * from './application/create-request-context'
+export * from './application/use-declaro'
+export * from './context/context'
+export * from './context/context-consumer'
+export * from './context/validators'
 export * from './dataflow'
 export * from './events'
 export * from './validation'
 export * from './timing'
-export * from './schema'
-export * from './helpers'
-export * from './interfaces'
-export * from './schema/formats'
+export * from './scope'
+export * from './errors/errors'
 export * from './pipelines'
+export * from './http/headers'
+export * from './http/request-context'
+export * from './http/request'
+export * from './http/url'
+export * from './auth/permission-validator'
+export * from './schema/model'
+export * from './schema/json-schema'
+export * from './schema/labels'
+export * from './schema/model-schema'
+export * from './schema/schema-mixin'
+export * from './schema/test/mock-model'
+
+export * from './shared/utils/action-descriptor'

package/src/pipelines/pipeline.test.ts

@@ -94,14 +94,16 @@ describe('Pipelines', () => {
                 number,
             }),
         )
-        const message = vi.fn((meta?: Meta) =>
-            meta?.positive
+        const message = vi.fn((meta: Meta | string): string =>
+            typeof meta === 'string'
+                ? meta
+                : meta?.positive
                 ? `${meta.number} is positive`
-                : meta.negative
+                : meta?.negative
                 ? `${meta.number} is negative`
-                : meta.zero
-                ? `${meta.number} is zero`
-                : `${meta.number} is not a number`,
+                : meta?.zero
+                ? `${meta?.number} is zero`
+                : `${meta?.number} is not a number`,
         )
 
         const originalPipeline = new Pipeline(initialInput<number>()).pipe(meta)
@@ -165,11 +167,11 @@ describe('Pipelines', () => {
 
             return meta?.positive
                 ? `${meta.number} is positive`
-                : meta.negative
+                : meta?.negative
                 ? `${meta.number} is negative`
-                : meta.zero
+                : meta?.zero
                 ? `${meta.number} is zero`
-                : `${meta.number} is not a number`
+                : `${meta?.number} is not a number`
         })
 
         const originalPipeline = new Pipeline(initialInput<number>()).pipe(meta)

package/src/schema/json-schema.ts

@@ -0,0 +1,3 @@
+import { type JSONSchema7 } from 'json-schema'
+
+export interface JSONSchema extends JSONSchema7 {}

package/src/schema/labels.ts

@@ -0,0 +1,30 @@
+import { capitalCase, camelCase, kebabCase, pascalCase, sentenceCase } from 'change-case'
+import pluralize from 'pluralize'
+
+export type ModelLabels = {
+    singularLabel: string
+    pluralLabel: string
+    singularSentence: string
+    pluralSentence: string
+    singularParameter: string
+    pluralParameter: string
+    singularSlug: string
+    pluralSlug: string
+    singularEntityName: string
+    pluralEntityName: string
+}
+
+export function getLabels(modelName: string, labels: Partial<ModelLabels> = {}): ModelLabels {
+    return {
+        singularLabel: capitalCase(pluralize(labels.singularLabel ?? modelName, 1)),
+        pluralLabel: capitalCase(pluralize(labels.pluralLabel ?? modelName, 10)),
+        singularSentence: sentenceCase(pluralize(labels.singularLabel ?? modelName, 1)),
+        pluralSentence: sentenceCase(pluralize(labels.pluralLabel ?? modelName, 10)),
+        singularParameter: camelCase(pluralize(labels.singularParameter ?? modelName, 1)),
+        pluralParameter: camelCase(pluralize(labels.pluralParameter ?? modelName, 10)),
+        singularSlug: kebabCase(pluralize(labels.singularSlug ?? modelName, 1)),
+        pluralSlug: kebabCase(pluralize(labels.pluralSlug ?? modelName, 10)),
+        singularEntityName: pascalCase(pluralize(labels.singularEntityName ?? modelName, 1)),
+        pluralEntityName: pascalCase(pluralize(labels.pluralEntityName ?? modelName, 10)),
+    }
+}

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

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod/v4'
+import { ModelSchema, type MergeMixins } from './model-schema'
+import { MockModel } from './test/mock-model'
+import type { InferModelOutput } from './model'
+import type { ShallowMerge, UniqueKeys } from '../typescript'
+
+describe('ModelSchema', () => {
+    it('should create a ModelSchema instance', () => {
+        const schema = ModelSchema.create('TestModel')
+        expect(schema).toBeInstanceOf(ModelSchema)
+        expect(schema.name).toBe('TestModel')
+    })
+
+    it('should support read definitions with MixinFactory', () => {
+        const schema = ModelSchema.create('Book').read({
+            detail: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+            lookup: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+        })
+
+        expect(schema.definition.detail).toBeInstanceOf(MockModel)
+        expect(schema.definition.lookup).toBeInstanceOf(MockModel)
+
+        const X = {} as any as InferModelOutput<(typeof schema)['definition']['lookup']>
+
+        expect(schema.definition.detail.name).toBe('BookDetail')
+        expect(schema.definition.lookup.name).toBe('BookLookup')
+    })
+
+    it('should support search definitions with MixinFactory', () => {
+        const schema = ModelSchema.create('Book').search({
+            filters: (h) =>
+                new MockModel(h.name, z.object({ title: z.string().optional(), author: z.string().optional() })),
+            summary: (h) => new MockModel(h.name, z.object({ id: z.string(), title: z.string() })),
+            sort: (h) =>
+                new MockModel(h.name, z.object({ title: z.enum(['asc', 'desc']), author: z.enum(['asc', 'desc']) })),
+        })
+
+        expect(schema.definition.filters).toBeInstanceOf(MockModel)
+        expect(schema.definition.summary).toBeInstanceOf(MockModel)
+        expect(schema.definition.filters.name).toBe('BookFilters')
+        expect(schema.definition.summary.name).toBe('BookSummary')
+    })
+
+    it('should support write definitions with MixinFactory', () => {
+        const schema = ModelSchema.create('Book').write({
+            input: (h) => new MockModel(h.name, z.object({ title: z.string(), author: z.string() })),
+        })
+
+        expect(schema.definition.input).toBeInstanceOf(MockModel)
+        expect(schema.definition.input.name).toBe('BookInput')
+    })
+
+    it('should define a primary key', () => {
+        const schema = ModelSchema.create('Book')
+            .read({
+                detail: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+                lookup: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+            })
+            .write({
+                input: (h) => new MockModel(h.name, z.object({ id: z.string(), title: z.string() })),
+            })
+            .entity({
+                primaryKey: 'id',
+            })
+
+        expect(schema.getEntityMetadata().primaryKey).toBe('id')
+    })
+
+    it('should allow redefinition of types', () => {
+        const schema = ModelSchema.create('Book')
+            .read({
+                detail: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+                lookup: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+            })
+            .write({
+                input: (h) => new MockModel(h.name, z.object({ id: z.string(), title: z.string() })),
+            })
+            .entity({
+                primaryKey: 'id',
+            })
+
+        const redefinedSchema = schema.read({
+            detail: (h) =>
+                new MockModel(
+                    h.name,
+                    z.object({ id: z.number(), name: z.string().optional(), age: z.number().optional() }),
+                ),
+            lookup: (h) => new MockModel(h.name, z.object({ id: z.number() })),
+        })
+
+        const patchedSchema = redefinedSchema.custom({
+            detail: () =>
+                new MockModel(
+                    'BookDetail',
+                    z.object({ id: z.string(), name: z.string(), foo: z.string(), bar: z.string() }),
+                ),
+        })
+
+        const detailSchema = redefinedSchema.definition.detail.toJSONSchema()
+        const patchedDetailSchema = patchedSchema.definition.detail.toJSONSchema()
+
+        expect(redefinedSchema.definition.detail).toBeInstanceOf(MockModel)
+        expect(Object.keys(detailSchema.properties ?? {})).toEqual(['id', 'name', 'age'])
+
+        expect(Object.keys(patchedDetailSchema.properties ?? {})).toEqual(['id', 'name', 'foo', 'bar'])
+    })
+
+    it('should be able to redefine schema without changes to the primary key', () => {
+        const schema = ModelSchema.create('Book')
+            .read({
+                detail: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+                lookup: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+            })
+            .write({
+                input: (h) => new MockModel(h.name, z.object({ id: z.string(), title: z.string() })),
+            })
+            .entity({
+                primaryKey: 'id',
+            })
+            .read({
+                detail: (h) => new MockModel(h.name, z.object({ uuid: z.string(), name: z.string() })),
+                lookup: (h) => new MockModel(h.name, z.object({ uuid: z.string(), name: z.string() })),
+            })
+
+        expect(schema.getEntityMetadata().primaryKey).toBe('id')
+    })
+})

package/src/schema/model-schema.ts

@@ -0,0 +1,197 @@
+import { merge } from '../dataflow'
+import type { Merge, ShallowMerge } from '../typescript'
+import { getLabels, type ModelLabels } from './labels'
+import { type InferModelInput } from './model'
+import {
+    buildMixin,
+    defineMixin,
+    type IAnyMixin,
+    type IMixin,
+    type IMixinHelper,
+    type IMixinHelpers,
+    type IMixinInput,
+    type InferMixinInput,
+} from './schema-mixin'
+import { MockModel } from './test/mock-model'
+import { z } from 'zod/v4'
+
+export type Subset<T> = {
+    [K in keyof T]?: T[K]
+}
+export type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+export type MergeMixins<TA extends IAnyMixin | undefined, TB extends IAnyMixin> = Simplify<
+    TA extends IAnyMixin ? ShallowMerge<TA, TB> : TB
+>
+
+export function getReadHelpers<TName extends Readonly<string>>(h: IMixinHelper<TName>) {
+    return {
+        detail: { name: h.name },
+        lookup: { name: `${h.name}Lookup` as const },
+    }
+}
+
+const readMixin = defineMixin((h) => ({
+    detail: {
+        name: `${h.name}Detail` as const,
+    },
+    lookup: {
+        name: `${h.name}Lookup` as const,
+    },
+}))
+export type ReadMixin<TName extends Readonly<string>> = ReturnType<typeof readMixin<TName>>
+
+const defaultMixin = defineMixin((h) => ({}))
+export type DefaultMixin<TName extends Readonly<string>> = ReturnType<typeof defaultMixin<TName>>
+
+const searchMixin = defineMixin((h) => ({
+    summary: { name: `${h.name}Summary` as const },
+    filters: { name: `${h.name}Filters` as const },
+    sort: { name: `${h.name}Sort` as const },
+}))
+export type SearchMixin<TName extends Readonly<string>> = ReturnType<typeof searchMixin<TName>>
+
+const writeMixin = defineMixin((h) => ({
+    input: { name: `${h.name}Input` as const },
+}))
+export type WriteMixin<TName extends Readonly<string>> = ReturnType<typeof writeMixin<TName>>
+
+export type IModelNames<T extends object> = {
+    [K in keyof T]: Readonly<string>
+}
+
+export type InferPKeyBaseType<T extends IAnyMixin | undefined> = T extends IAnyMixin
+    ? T['lookup'] extends object
+        ? keyof InferModelInput<T['lookup']> | undefined
+        : undefined
+    : undefined
+
+export interface IModelEntityMetadata {
+    primaryKey: string
+}
+
+export class ModelSchema<
+    TName extends Readonly<string> = Readonly<string>,
+    T extends IAnyMixin | undefined = undefined,
+    TEntityMeta extends IModelEntityMetadata | undefined = undefined,
+> {
+    static create<TName extends Readonly<string>>(name: TName): ModelSchema<TName> {
+        return new ModelSchema(name)
+    }
+
+    public readonly definition: Simplify<T>
+    public readonly name: TName
+    protected readonly entityMetadata: TEntityMeta
+
+    constructor(name: TName, definition: T = {} as T, entityMetadata?: TEntityMeta) {
+        this.definition = definition
+        this.name = name
+        this.entityMetadata = entityMetadata!
+    }
+
+    get labels(): ModelLabels {
+        return getLabels(this.name)
+    }
+
+    get helper(): IMixinHelper<TName> {
+        return {
+            name: this.name,
+        }
+    }
+
+    custom<TInput extends IMixinInput>(input: TInput): ModelSchema<TName, MergeMixins<T, IMixin<TInput>>, TEntityMeta> {
+        const helpers: IMixinHelpers<TInput> = Object.keys(input).reduce((acc: any, key) => {
+            const helper = this.helper
+            acc[key] = helper
+            return acc
+        }, {} as IMixinHelpers<TInput>)
+        const definition = buildMixin(helpers, input as any)
+
+        return new ModelSchema(
+            this.name,
+            {
+                ...this.definition,
+                ...definition,
+            },
+            this.entityMetadata,
+        ) as any
+    }
+
+    read<TInput extends InferMixinInput<ReadMixin<TName>>>(
+        input: TInput,
+    ): ModelSchema<TName, MergeMixins<T, IMixin<TInput>>, TEntityMeta> {
+        const helpers = readMixin(this.helper)
+        const definition = buildMixin(helpers, input)
+
+        return new ModelSchema(
+            this.name,
+            {
+                ...this.definition,
+                ...definition,
+            },
+            this.entityMetadata,
+        ) as any
+    }
+
+    search<TInput extends InferMixinInput<SearchMixin<TName>>>(
+        input: TInput,
+    ): ModelSchema<TName, MergeMixins<T, IMixin<TInput>>> {
+        const helpers = searchMixin(this.helper)
+        const definition = buildMixin(helpers, input)
+
+        return new ModelSchema(
+            this.name,
+            {
+                ...this.definition,
+                ...definition,
+            },
+            this.entityMetadata,
+        ) as any
+    }
+
+    write<TInput extends InferMixinInput<WriteMixin<TName>>>(
+        input: TInput,
+    ): ModelSchema<TName, MergeMixins<T, IMixin<TInput>>> {
+        const helpers = writeMixin(this.helper)
+        const definition = buildMixin(helpers, input)
+
+        return new ModelSchema(
+            this.name,
+            {
+                ...this.definition,
+                ...definition,
+            },
+            this.entityMetadata,
+        ) as any
+    }
+
+    entity<
+        TEntityMeta extends {
+            primaryKey: InferPKeyBaseType<T>
+        },
+    >(meta: TEntityMeta): ModelSchema<TName, T, TEntityMeta extends IModelEntityMetadata ? TEntityMeta : undefined> {
+        const lookupMeta = this.definition?.['lookup']?.toJSONSchema()
+        const lookupKeys = Object.keys(lookupMeta?.properties ?? {})
+
+        const metaIsValid = meta && typeof meta.primaryKey === 'string' && lookupKeys.includes(meta.primaryKey)
+        return new ModelSchema<TName, T, TEntityMeta extends IModelEntityMetadata ? TEntityMeta : undefined>(
+            this.name,
+            this.definition,
+            metaIsValid ? (meta as any) : undefined,
+        )
+    }
+
+    getEntityMetadata(): TEntityMeta {
+        return this.entityMetadata
+    }
+}
+
+export type AnyModelSchema = ModelSchema<any, any, any>
+
+const test = ModelSchema.create('Test').read({
+    detail: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+    lookup: (h) => new MockModel(h.name, z.object({ id: z.string(), name: z.string() })),
+})
+
+const d = test.definition
+const l = {} as any as keyof InferModelInput<typeof test.definition.lookup>