@declaro/core 2.0.0-y.0 → 2.1.0

package/src/schema/model.ts

@@ -0,0 +1,143 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import type { JSONSchema } from './json-schema'
+import { SystemError, ValidationError } from '../errors/errors'
+import { getLabels, type ModelLabels } from './labels'
+
+export interface ModelValidationOptions {
+    strict?: boolean
+}
+
+export interface ModelSchemaOptions {
+    includePrivateFields?: boolean
+}
+
+export function getDefaultModelSchemaOptions(): ModelSchemaOptions {
+    return {
+        includePrivateFields: false,
+    }
+}
+
+export abstract class Model<TName extends Readonly<string>, TSchema extends StandardSchemaV1>
+    implements StandardSchemaV1<StandardSchemaV1.InferInput<TSchema>, StandardSchemaV1.InferOutput<TSchema>>
+{
+    public readonly name: TName
+    /**
+     * @warning You may not need to use this property directly.
+     * Use the `validate` method instead to ensure proper validation and error handling.
+     * Use the `toJSONSchema` method to get the JSON Schema representation for introspection or documentation.
+     */
+    public readonly schema: TSchema
+
+    constructor(name: TName, schema: TSchema) {
+        if (!schema || !schema['~standard'] || schema['~standard'].version !== 1) {
+            throw new SystemError(`Invalid schema provided for model "${name}". Must implement StandardSchemaV1.`)
+        }
+
+        this.name = name
+        this.schema = schema
+    }
+
+    stripExcludedFields(value: StandardSchemaV1.InferInput<TSchema>): StandardSchemaV1.InferInput<TSchema> {
+        const meta = this.toJSONSchema({
+            includePrivateFields: true,
+        })
+
+        const excludedKeys = Object.keys(meta.properties ?? {}).filter((key) => {
+            const property = meta.properties?.[key]
+            return !!property && typeof property === 'object' && property.private === true
+        })
+
+        if (value && excludedKeys.length > 0) {
+            excludedKeys.forEach((key) => {
+                delete value[key]
+            })
+        }
+
+        return value
+    }
+
+    async validate(
+        value: StandardSchemaV1.InferInput<TSchema>,
+        options?: ModelValidationOptions,
+    ): Promise<StandardSchemaV1.Result<StandardSchemaV1.InferOutput<TSchema>>> {
+        const meta = this.toJSONSchema()
+
+        value = this.stripExcludedFields(value)
+
+        const result = await this.schema['~standard'].validate(value)
+
+        if (result.issues) {
+            const issues = result.issues.map((issue) => {
+                let schema: JSONSchema | undefined = meta
+                let field: string | undefined = undefined
+                issue.path?.forEach((segment) => {
+                    field = segment as string
+                    const nested = schema?.properties?.[segment as string] as JSONSchema | undefined
+                    if (nested) {
+                        schema = nested
+                    } else {
+                        schema = undefined
+                    }
+                })
+
+                let title = schema?.title
+                if (!title && field) {
+                    const labels = getLabels(field)
+
+                    title = labels?.singularLabel
+                }
+
+                const message = title ? `Validation failed for field "${title}": ${issue.message}` : issue.message
+
+                return {
+                    ...issue,
+                    message,
+                }
+            })
+
+            const message = issues.map((issue) => issue.message)?.[0]
+
+            if (options?.strict === false) {
+                return {
+                    issues,
+                }
+            }
+
+            throw new ValidationError(message, { result })
+        }
+
+        return result
+    }
+
+    get labels(): ModelLabels {
+        return getLabels(this.name)
+    }
+
+    abstract toJSONSchema(options?: ModelSchemaOptions): JSONSchema
+
+    // Implementing StandardSchemaV1 interface
+    get version(): number {
+        return 1
+    }
+
+    // Correcting the '~standard' property implementation to match StandardSchemaV1
+    get '~standard'(): StandardSchemaV1['~standard'] {
+        return {
+            version: 1,
+            vendor: 'Declaro',
+            validate: this.validate.bind(this),
+        }
+    }
+}
+
+export type UnwrapModelSchema<T extends Model<any, any>> = T extends Model<any, infer S> ? S : never
+export type InferModelOutput<T extends Model<any, any>> = StandardSchemaV1.InferOutput<UnwrapModelSchema<T>>
+export type InferModelInput<T extends Model<any, any>> = StandardSchemaV1.InferInput<UnwrapModelSchema<T>>
+
+export type IAnyModel = Model<Readonly<string>, StandardSchemaV1>
+
+export interface IModelHelper<TNameRecommendation extends Readonly<string>> {
+    name: TNameRecommendation
+}
+
+export type ModelFactory<TName extends Readonly<string>> = (helper: IModelHelper<TName>) => IAnyModel

package/src/schema/schema-mixin.ts

@@ -0,0 +1,51 @@
+import { type IAnyModel, type ModelFactory } from './model'
+
+export interface IAnyMixin {
+    [key: string]: IAnyModel
+}
+
+export type IMixin<TInput extends IMixinInput> = {
+    [K in keyof TInput]: TInput[K] extends ModelFactory<any> ? ReturnType<TInput[K]> : never
+}
+
+export interface IMixinInput {
+    [key: string]: ModelFactory<any>
+}
+
+export interface IMixinHelper<TName extends Readonly<string>> {
+    name: TName
+}
+
+export type IMixinHelpers<TMixin extends IMixinInput> = {
+    [K in keyof TMixin]: TMixin[K] extends ModelFactory<infer TName> ? IMixinHelper<TName> : never
+}
+
+export function buildMixin<TMixin extends IMixinHelpers<any>>(
+    helpers: TMixin,
+    input: InferMixinInput<TMixin>,
+): IMixin<InferMixinInput<TMixin>> {
+    const mixin: IAnyMixin = {}
+    for (const key in helpers) {
+        const helper = helpers[key]
+        if (typeof helper?.name === 'string') {
+            mixin[key] = input[key](helper)
+        } else {
+            throw new Error(`Invalid helper name for key "${key}": ${helper.name}`)
+        }
+    }
+    return mixin as IMixin<InferMixinInput<TMixin>>
+}
+
+export type MixinFn<THelpers extends IMixinHelpers<any>> = <TName extends Readonly<string>>(
+    helper: IMixinHelper<TName>,
+) => THelpers
+
+export function defineMixin<TInput extends IMixinHelpers<any>, Fn extends MixinFn<TInput>>(fn: Fn) {
+    return fn
+}
+
+export type InferMixinInput<T extends IMixinHelpers<any>> = {
+    [K in keyof T]: T[K] extends IMixinHelper<infer TName> ? ModelFactory<TName> : never
+}
+
+export type InferMixinSchema<TMixin extends IMixinHelpers<any>> = IMixin<InferMixinInput<TMixin>>

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

@@ -0,0 +1,19 @@
+import { z } from 'zod/v4'
+import type { $ZodType } from 'zod/v4/core'
+import type { JSONSchema } from '../json-schema'
+import { Model, type ModelSchemaOptions } from '../model'
+import { stripPrivateFieldsFromSchema } from '../../shared/utils/schema-utils'
+
+export class MockModel<TName extends Readonly<string>, TSchema extends $ZodType<any>> extends Model<TName, TSchema> {
+    constructor(name: TName, schema: TSchema) {
+        super(name, schema)
+    }
+
+    toJSONSchema(options?: ModelSchemaOptions): JSONSchema {
+        const jsonSchema = z.toJSONSchema(this.schema)
+        if (options?.includePrivateFields !== true) {
+            stripPrivateFieldsFromSchema(jsonSchema as JSONSchema)
+        }
+        return jsonSchema as JSONSchema
+    }
+}

package/src/scope/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Base scope interfaces for @declaro/core
+ *
+ * Users can augment these interfaces by creating their own declaration file:
+ *
+ * ```typescript
+ * // types/scope.d.ts
+ * declare module '#scope' {
+ *   interface AppScope {
+ *     // Add your app-level scope properties
+ *     config: MyAppConfig
+ *   }
+ *
+ *   interface RequestScope {
+ *     // Add your request-level scope properties
+ *     user: User
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Base application scope interface.
+ * This represents data that is available throughout the entire application lifecycle.
+ */
+export interface AppScope {}
+
+/**
+ * Base request scope interface.
+ * This represents data that is available for the duration of a single request.
+ * Extends AppScope to inherit application-level data.
+ */
+export interface RequestScope extends AppScope {}

package/src/shared/utils/action-descriptor.test.ts

@@ -0,0 +1,182 @@
+import { describe, expect, it } from 'bun:test'
+import { ActionDescriptor } from './action-descriptor'
+
+describe('ActionDescriptor', () => {
+    describe('constructor', () => {
+        it('should initialize with input values', () => {
+            const input = { namespace: 'auth', resource: 'user', action: 'create', scope: 'admin' }
+            const descriptor = new ActionDescriptor(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('user')
+            expect(descriptor.action).toBe('create')
+            expect(descriptor.scope).toBe('admin')
+        })
+
+        it('should initialize with default values if input is missing', () => {
+            const input = {}
+            const descriptor = new ActionDescriptor(input)
+
+            expect(descriptor.namespace).toBe('global')
+            expect(descriptor.resource).toBe('*')
+            expect(descriptor.action).toBe('*')
+            expect(descriptor.scope).toBeUndefined()
+        })
+    })
+
+    describe('update', () => {
+        it('should update descriptor values', () => {
+            const input = { namespace: 'auth', resource: 'user', action: 'create', scope: 'admin' }
+            const descriptor = new ActionDescriptor(input)
+
+            descriptor.update({ resource: 'group', action: 'delete' })
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('group')
+            expect(descriptor.action).toBe('delete')
+            expect(descriptor.scope).toBe('admin')
+        })
+
+        it('should retain existing values if update input is missing', () => {
+            const input = { namespace: 'auth', resource: 'user', action: 'create', scope: 'admin' }
+            const descriptor = new ActionDescriptor(input)
+
+            descriptor.update({})
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('user')
+            expect(descriptor.action).toBe('create')
+            expect(descriptor.scope).toBe('admin')
+        })
+    })
+
+    describe('toJSON', () => {
+        it('should return a JSON representation of the descriptor', () => {
+            const input = { namespace: 'auth', resource: 'user', action: 'create', scope: 'admin' }
+            const descriptor = new ActionDescriptor(input)
+
+            const json = descriptor.toJSON()
+            expect(json).toEqual(input)
+        })
+    })
+
+    describe('toString', () => {
+        it('should return a string representation of the descriptor', () => {
+            const input = { namespace: 'auth', resource: 'user', action: 'create', scope: 'admin' }
+            const descriptor = new ActionDescriptor(input)
+
+            const str = descriptor.toString()
+            expect(str).toBe('auth::user.create:admin')
+        })
+
+        it('should handle missing scope gracefully', () => {
+            const input = { namespace: 'auth', resource: 'user', action: 'create' }
+            const descriptor = new ActionDescriptor(input)
+
+            const str = descriptor.toString()
+            expect(str).toBe('auth::user.create')
+        })
+    })
+
+    describe('parse', () => {
+        it('should parse a string into an ActionDescriptor', () => {
+            const descriptor = new ActionDescriptor({ namespace: 'global' })
+
+            const input = 'auth::user.create:admin'
+            descriptor.parse(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('user')
+            expect(descriptor.action).toBe('create')
+            expect(descriptor.scope).toBe('admin')
+        })
+
+        it('should handle missing scope gracefully', () => {
+            const descriptor = new ActionDescriptor({ namespace: 'global' })
+
+            const input = 'auth::user.create'
+            descriptor.parse(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('user')
+            expect(descriptor.action).toBe('create')
+            expect(descriptor.scope).toBeUndefined()
+        })
+
+        it('should use default values for missing parts', () => {
+            const descriptor = new ActionDescriptor({ namespace: 'global' })
+
+            const input = 'auth'
+            descriptor.parse(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('*')
+            expect(descriptor.action).toBe('*')
+            expect(descriptor.scope).toBeUndefined()
+        })
+    })
+
+    describe('fromJSON', () => {
+        it('should create an ActionDescriptor from a JSON object', () => {
+            const input = { namespace: 'auth', resource: 'user', action: 'create', scope: 'admin' }
+            const descriptor = ActionDescriptor.fromJSON(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('user')
+            expect(descriptor.action).toBe('create')
+            expect(descriptor.scope).toBe('admin')
+        })
+
+        it('should handle missing scope gracefully', () => {
+            const input = { namespace: 'auth', resource: 'user', action: 'create' }
+            const descriptor = ActionDescriptor.fromJSON(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('user')
+            expect(descriptor.action).toBe('create')
+            expect(descriptor.scope).toBeUndefined()
+        })
+
+        it('should use default values for missing parts', () => {
+            const input = { namespace: 'auth', resource: '*', action: '*', scope: undefined }
+            const descriptor = ActionDescriptor.fromJSON(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('*')
+            expect(descriptor.action).toBe('*')
+            expect(descriptor.scope).toBeUndefined()
+        })
+    })
+
+    describe('fromString', () => {
+        it('should create an ActionDescriptor from a string', () => {
+            const input = 'auth::user.create:admin'
+            const descriptor = ActionDescriptor.fromString(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('user')
+            expect(descriptor.action).toBe('create')
+            expect(descriptor.scope).toBe('admin')
+        })
+
+        it('should handle missing scope gracefully', () => {
+            const input = 'auth::user.create'
+            const descriptor = ActionDescriptor.fromString(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('user')
+            expect(descriptor.action).toBe('create')
+            expect(descriptor.scope).toBeUndefined()
+        })
+
+        it('should use default values for missing parts', () => {
+            const input = 'auth'
+            const descriptor = ActionDescriptor.fromString(input)
+
+            expect(descriptor.namespace).toBe('auth')
+            expect(descriptor.resource).toBe('*')
+            expect(descriptor.action).toBe('*')
+            expect(descriptor.scope).toBeUndefined()
+        })
+    })
+})

package/src/shared/utils/action-descriptor.ts

@@ -0,0 +1,102 @@
+import { kebabCase } from 'change-case'
+
+export interface IActionDescriptorInput {
+    namespace?: string
+    resource?: string
+    action?: string
+    scope?: string
+}
+
+export interface IActionDescriptor {
+    namespace: string
+    resource: string
+    action: string
+    scope?: string
+}
+
+export class ActionDescriptor implements IActionDescriptor {
+    protected readonly descriptor: IActionDescriptorInput
+
+    constructor(input: IActionDescriptorInput) {
+        this.descriptor = {}
+        this.update(input)
+    }
+
+    update(input: IActionDescriptorInput) {
+        this.descriptor.namespace = this.parameterize(input.namespace ?? this.descriptor.namespace)
+        this.descriptor.resource = this.parameterize(input.resource ?? this.descriptor.resource)
+        this.descriptor.action = input.action ?? this.descriptor.action
+        this.descriptor.scope = this.parameterize(input.scope ?? this.descriptor.scope)
+
+        return this
+    }
+
+    get namespace(): string {
+        return this.descriptor.namespace ?? 'global'
+    }
+
+    get resource(): string {
+        return this.descriptor.resource ?? '*'
+    }
+
+    get action(): string {
+        return this.descriptor.action ?? '*'
+    }
+
+    get scope(): string | undefined {
+        return this.descriptor.scope
+    }
+
+    toString(): string {
+        return `${this.namespace}::${this.resource}.${this.action}${this.scope ? `:${this.scope}` : ''}`
+    }
+
+    toJSON(): IActionDescriptor {
+        return {
+            namespace: this.namespace,
+            resource: this.resource,
+            action: this.action,
+            scope: this.scope,
+        }
+    }
+
+    parse(input: string): ActionDescriptor {
+        let remainder = input.trim()
+
+        const [namespace, ...rest] = remainder.split('::').filter((s) => s.trim() !== '')
+        remainder = rest.join('::').trim()
+
+        const [resource, ...rest2] = remainder.split('.').filter((s) => s.trim() !== '')
+        remainder = rest2.join('.').trim()
+
+        const [action, ...rest3] = remainder.split(':').filter((s) => s.trim() !== '')
+        remainder = rest3.join(':').trim()
+
+        const [scope] = remainder.split(':').filter((s) => s.trim() !== '')
+
+        this.update({
+            namespace: namespace,
+            resource: resource,
+            action: action,
+            scope: scope,
+        })
+
+        return this
+    }
+
+    static fromString(input: string): ActionDescriptor {
+        const descriptor = new ActionDescriptor({ namespace: 'global', resource: '*', action: '*' })
+        return descriptor.parse(input)
+    }
+
+    static fromJSON(json: IActionDescriptorInput): ActionDescriptor {
+        return new ActionDescriptor(json)
+    }
+
+    protected parameterize(string?: string) {
+        if (!string || string === '*') {
+            return string
+        }
+        return kebabCase(string)
+    }
+}

package/src/shared/utils/schema-utils.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import type { JSONSchema } from '../../schema/json-schema'
+import { stripPrivateFieldsFromSchema } from './schema-utils'
+
+describe('Schema Utils', () => {
+    it('should strip private fields from schema', () => {
+        const schema: JSONSchema = {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                name: { type: 'string' },
+                secret: { type: 'string', private: true },
+                internalNote: { type: 'string', hidden: true },
+            },
+        }
+
+        const stripped = stripPrivateFieldsFromSchema(schema)
+
+        // The return value should have the private field removed
+        expect(stripped.properties).toBeDefined()
+        expect(stripped.properties?.['id']).toBeDefined()
+        expect(stripped.properties?.['name']).toBeDefined()
+        expect(stripped.properties?.['secret']).toBeUndefined()
+        expect(stripped.properties?.['internalNote']).toBeDefined()
+
+        // The original schema should also have the private field removed
+        expect(schema.properties).toBeDefined()
+        expect(schema.properties?.['id']).toBeDefined()
+        expect(schema.properties?.['name']).toBeDefined()
+        expect(schema.properties?.['secret']).toBeUndefined()
+        expect(schema.properties?.['internalNote']).toBeDefined()
+    })
+})

package/src/shared/utils/schema-utils.ts

@@ -0,0 +1,17 @@
+import type { JSONSchema } from '../../schema/json-schema'
+
+export function stripPrivateFieldsFromSchema(schema: JSONSchema): JSONSchema {
+    if (typeof schema?.properties === 'object') {
+        for (const key of Object.keys(schema.properties)) {
+            const property = schema.properties[key]
+            if (typeof property === 'object') {
+                if (property.private === true) {
+                    delete schema.properties[key]
+                } else {
+                    stripPrivateFieldsFromSchema(property)
+                }
+            }
+        }
+    }
+    return schema
+}