@declaro/data 2.0.0-beta.8 → 2.0.0-beta.81

package/src/application/read-only-model-controller.test.ts

@@ -0,0 +1,327 @@
+import { AuthValidator, getMockAuthSession, mockAuthConfig, MockAuthService } from '@declaro/auth'
+import { EventManager, PermissionError } from '@declaro/core'
+import { beforeEach, describe, expect, it } from 'bun:test'
+import { ReadOnlyModelService } from '../domain/services/read-only-model-service'
+import { MockBookSchema } from '../test/mock/models/mock-book-models'
+import { MockMemoryRepository } from '../test/mock/repositories/mock-memory-repository'
+import { ReadOnlyModelController } from './read-only-model-controller'
+
+describe('ReadOnlyModelController', () => {
+    const namespace = 'books'
+    const mockSchema = MockBookSchema
+    const authService = new MockAuthService(mockAuthConfig)
+
+    let repository: MockMemoryRepository<typeof mockSchema>
+    let service: ReadOnlyModelService<typeof mockSchema>
+    let authValidator: AuthValidator
+    let invalidAuthValidator: AuthValidator
+
+    beforeEach(() => {
+        repository = new MockMemoryRepository({ schema: mockSchema })
+        authValidator = new AuthValidator(
+            getMockAuthSession({
+                claims: ['books::book.read:all'],
+            }),
+            authService,
+        )
+        invalidAuthValidator = new AuthValidator(
+            getMockAuthSession({
+                claims: ['authors::author.read:all'],
+            }),
+            authService,
+        )
+        service = new ReadOnlyModelService({
+            repository,
+            emitter: new EventManager(),
+            schema: mockSchema,
+            namespace,
+        })
+    })
+
+    it('should load a single record if permissions are valid', async () => {
+        const controller = new ReadOnlyModelController(service, authValidator)
+
+        const input = { id: 42, title: 'Test Book', author: 'Author Name', publishedDate: new Date() }
+        await repository.create(input)
+
+        const record = await controller.load({ id: 42 })
+
+        expect(record).toEqual(input)
+    })
+
+    it('should throw PermissionError if permissions are invalid for load', async () => {
+        const controller = new ReadOnlyModelController(service, invalidAuthValidator)
+
+        await expect(controller.load({ id: 42 })).rejects.toThrow(PermissionError)
+    })
+
+    it('should load multiple records if permissions are valid', async () => {
+        const controller = new ReadOnlyModelController(service, authValidator)
+
+        const input1 = { id: 42, title: 'Test Book 1', author: 'Author Name 1', publishedDate: new Date() }
+        const input2 = { id: 43, title: 'Test Book 2', author: 'Author Name 2', publishedDate: new Date() }
+        await repository.create(input1)
+        await repository.create(input2)
+
+        const records = await controller.loadMany([{ id: 42 }, { id: 43 }])
+
+        expect(records).toEqual([input1, input2])
+    })
+
+    it('should throw PermissionError if permissions are invalid for loadMany', async () => {
+        const controller = new ReadOnlyModelController(service, invalidAuthValidator)
+
+        await expect(controller.loadMany([{ id: 42 }, { id: 43 }])).rejects.toThrow(PermissionError)
+    })
+
+    it('should search for records if permissions are valid', async () => {
+        const controller = new ReadOnlyModelController(service, authValidator)
+
+        const input1 = { id: 42, title: 'Test Book 1', author: 'Author Name 1', publishedDate: new Date() }
+        const input2 = { id: 43, title: 'Test Book 2', author: 'Author Name 2', publishedDate: new Date() }
+        await repository.create(input1)
+        await repository.create(input2)
+
+        const results = await controller.search({ text: 'Test' })
+
+        expect(results.results).toEqual([input1, input2])
+        expect(results.pagination.total).toBe(2)
+    })
+
+    it('should throw PermissionError if permissions are invalid for search', async () => {
+        const controller = new ReadOnlyModelController(service, invalidAuthValidator)
+
+        await expect(controller.search({ text: 'Test' })).rejects.toThrow(PermissionError)
+    })
+
+    it('should handle search with pagination options', async () => {
+        const controller = new ReadOnlyModelController(service, authValidator)
+
+        // Create 5 items
+        for (let i = 1; i <= 5; i++) {
+            await repository.create({
+                id: i,
+                title: `Test Book ${i}`,
+                author: `Author ${i}`,
+                publishedDate: new Date(),
+            })
+        }
+
+        const results = await controller.search(
+            {},
+            {
+                pagination: { page: 1, pageSize: 2 },
+            },
+        )
+
+        expect(results.results).toHaveLength(2)
+        expect(results.pagination.page).toBe(1)
+        expect(results.pagination.pageSize).toBe(2)
+        expect(results.pagination.total).toBe(5)
+        expect(results.pagination.totalPages).toBe(3)
+    })
+
+    it('should handle search with sort options', async () => {
+        const controller = new ReadOnlyModelController(service, authValidator)
+
+        const input1 = { id: 1, title: 'Z Book', author: 'Author A', publishedDate: new Date() }
+        const input2 = { id: 2, title: 'A Book', author: 'Author B', publishedDate: new Date() }
+        await repository.create(input1)
+        await repository.create(input2)
+
+        const results = await controller.search(
+            {},
+            {
+                sort: [{ title: 'asc' }],
+            },
+        )
+
+        expect(results.results.map((r) => r.title)).toEqual(['A Book', 'Z Book'])
+        expect(results.pagination.total).toBe(2)
+    })
+
+    it('should handle search with combined options', async () => {
+        const repositoryWithFilter = new MockMemoryRepository({
+            schema: mockSchema,
+            filter: (data, filters) => {
+                if (filters.text) {
+                    return data.title.toLowerCase().includes(filters.text.toLowerCase())
+                }
+                return true
+            },
+        })
+
+        const serviceWithFilter = new ReadOnlyModelService({
+            repository: repositoryWithFilter,
+            emitter: new EventManager(),
+            namespace,
+            schema: mockSchema,
+        })
+
+        const controller = new ReadOnlyModelController(serviceWithFilter, authValidator)
+
+        await repositoryWithFilter.create({ title: 'Test Z Book', author: 'Author 1', publishedDate: new Date() })
+        await repositoryWithFilter.create({ title: 'Test A Book', author: 'Author 2', publishedDate: new Date() })
+        await repositoryWithFilter.create({ title: 'Other Book', author: 'Author 3', publishedDate: new Date() })
+
+        const results = await controller.search(
+            { text: 'Test' },
+            {
+                sort: [{ title: 'asc' }],
+                pagination: { page: 1, pageSize: 1 },
+            },
+        )
+
+        expect(results.results).toHaveLength(1)
+        expect(results.results[0].title).toBe('Test A Book')
+        expect(results.pagination.total).toBe(2)
+        expect(results.pagination.totalPages).toBe(2)
+    })
+
+    it('should count records if permissions are valid', async () => {
+        const controller = new ReadOnlyModelController(service, authValidator)
+
+        const input1 = { id: 1, title: 'Test Book 1', author: 'Author Name', publishedDate: new Date() }
+        const input2 = { id: 2, title: 'Test Book 2', author: 'Author Name', publishedDate: new Date() }
+        await repository.create(input1)
+        await repository.create(input2)
+
+        const count = await controller.count({})
+
+        expect(count).toBe(2)
+    })
+
+    it('should throw PermissionError if permissions are invalid for count', async () => {
+        const controller = new ReadOnlyModelController(service, invalidAuthValidator)
+
+        await expect(controller.count({})).rejects.toThrow(PermissionError)
+    })
+
+    describe('granular permission testing', () => {
+        it('should allow load with specific load permission', async () => {
+            const loadOnlyValidator = new AuthValidator(
+                getMockAuthSession({
+                    claims: ['books::book.load:all'],
+                }),
+                authService,
+            )
+            const controller = new ReadOnlyModelController(service, loadOnlyValidator)
+
+            const input = { id: 42, title: 'Test Book', author: 'Author Name', publishedDate: new Date() }
+            await repository.create(input)
+
+            const record = await controller.load({ id: 42 })
+
+            expect(record).toEqual(input)
+        })
+
+        it('should allow loadMany with specific loadMany permission', async () => {
+            const loadManyOnlyValidator = new AuthValidator(
+                getMockAuthSession({
+                    claims: ['books::book.loadMany:all'],
+                }),
+                authService,
+            )
+            const controller = new ReadOnlyModelController(service, loadManyOnlyValidator)
+
+            const input1 = { id: 42, title: 'Test Book 1', author: 'Author Name 1', publishedDate: new Date() }
+            const input2 = { id: 43, title: 'Test Book 2', author: 'Author Name 2', publishedDate: new Date() }
+            await repository.create(input1)
+            await repository.create(input2)
+
+            const records = await controller.loadMany([{ id: 42 }, { id: 43 }])
+
+            expect(records).toEqual([input1, input2])
+        })
+
+        it('should allow search with specific search permission', async () => {
+            const searchOnlyValidator = new AuthValidator(
+                getMockAuthSession({
+                    claims: ['books::book.search:all'],
+                }),
+                authService,
+            )
+            const controller = new ReadOnlyModelController(service, searchOnlyValidator)
+
+            const input1 = { id: 42, title: 'Test Book 1', author: 'Author Name 1', publishedDate: new Date() }
+            const input2 = { id: 43, title: 'Test Book 2', author: 'Author Name 2', publishedDate: new Date() }
+            await repository.create(input1)
+            await repository.create(input2)
+
+            const results = await controller.search({ text: 'Test' })
+
+            expect(results.results).toEqual([input1, input2])
+            expect(results.pagination.total).toBe(2)
+        })
+
+        it('should allow count with specific count permission', async () => {
+            const countOnlyValidator = new AuthValidator(
+                getMockAuthSession({
+                    claims: ['books::book.count:all'],
+                }),
+                authService,
+            )
+            const controller = new ReadOnlyModelController(service, countOnlyValidator)
+
+            const input1 = { id: 1, title: 'Test Book 1', author: 'Author Name', publishedDate: new Date() }
+            const input2 = { id: 2, title: 'Test Book 2', author: 'Author Name', publishedDate: new Date() }
+            await repository.create(input1)
+            await repository.create(input2)
+
+            const count = await controller.count({})
+
+            expect(count).toBe(2)
+        })
+
+        it('should reject operations with wrong namespace permissions', async () => {
+            const wrongNamespaceValidator = new AuthValidator(
+                getMockAuthSession({
+                    claims: ['users::user.read:all'], // Wrong namespace
+                }),
+                authService,
+            )
+            const controller = new ReadOnlyModelController(service, wrongNamespaceValidator)
+
+            await expect(controller.load({ id: 42 })).rejects.toThrow(PermissionError)
+            await expect(controller.loadMany([{ id: 42 }])).rejects.toThrow(PermissionError)
+            await expect(controller.search({})).rejects.toThrow(PermissionError)
+            await expect(controller.count({})).rejects.toThrow(PermissionError)
+        })
+
+        it('should reject operations with wrong resource permissions', async () => {
+            const wrongResourceValidator = new AuthValidator(
+                getMockAuthSession({
+                    claims: ['books::author.read:all'], // Wrong resource
+                }),
+                authService,
+            )
+            const controller = new ReadOnlyModelController(service, wrongResourceValidator)
+
+            await expect(controller.load({ id: 42 })).rejects.toThrow(PermissionError)
+            await expect(controller.loadMany([{ id: 42 }])).rejects.toThrow(PermissionError)
+            await expect(controller.search({})).rejects.toThrow(PermissionError)
+            await expect(controller.count({})).rejects.toThrow(PermissionError)
+        })
+
+        it('should allow all read operations with general read permission', async () => {
+            // This is already tested in the main tests, but including here for completeness
+            const controller = new ReadOnlyModelController(service, authValidator) // authValidator has read:all
+
+            const input = { id: 42, title: 'Test Book', author: 'Author Name', publishedDate: new Date() }
+            await repository.create(input)
+
+            // Test all operations work with general read permission
+            const loadResult = await controller.load({ id: 42 })
+            expect(loadResult).toEqual(input)
+
+            const loadManyResult = await controller.loadMany([{ id: 42 }])
+            expect(loadManyResult).toEqual([input])
+
+            const searchResult = await controller.search({})
+            expect(searchResult.results).toEqual([input])
+
+            const countResult = await controller.count({})
+            expect(countResult).toBe(1)
+        })
+    })
+})

package/src/application/read-only-model-controller.ts

@@ -0,0 +1,61 @@
+import type { AuthValidator } from '@declaro/auth'
+import {} from '@declaro/auth'
+import type { AnyModelSchema } from '@declaro/core'
+import type { ILoadOptions, ISearchOptions, ReadOnlyModelService } from '../domain/services/read-only-model-service'
+import type { InferDetail, InferFilters, InferLookup, InferSearchResults } from '../shared/utils/schema-inference'
+
+export class ReadOnlyModelController<TSchema extends AnyModelSchema> {
+    constructor(
+        protected readonly service: ReadOnlyModelService<TSchema>,
+        protected readonly authValidator: AuthValidator,
+    ) {}
+
+    async load(lookup: InferLookup<TSchema>, options?: ILoadOptions): Promise<InferDetail<TSchema>> {
+        this.authValidator.validatePermissions((v) =>
+            v.someOf([
+                this.service.getDescriptor('load', '*').toString(),
+                this.service.getDescriptor('read', '*').toString(),
+            ]),
+        )
+        return this.service.load(lookup, options)
+    }
+
+    async loadMany(lookups: InferLookup<TSchema>[], options?: ILoadOptions): Promise<InferDetail<TSchema>[]> {
+        this.authValidator.validatePermissions((v) =>
+            v.someOf([
+                this.service.getDescriptor('loadMany', '*').toString(),
+                this.service.getDescriptor('read', '*').toString(),
+            ]),
+        )
+        return this.service.loadMany(lookups, options)
+    }
+
+    async search(
+        input: InferFilters<TSchema>,
+        options?: ISearchOptions<TSchema>,
+    ): Promise<InferSearchResults<TSchema>> {
+        this.authValidator.validatePermissions((v) =>
+            v.someOf([
+                this.service.getDescriptor('search', '*').toString(),
+                this.service.getDescriptor('read', '*').toString(),
+            ]),
+        )
+        return this.service.search(input, options)
+    }
+
+    /**
+     * Count the number of records matching the given filters.
+     * @param input The filters to apply to the count operation.
+     * @param options Additional options for the count operation.
+     * @returns The count of matching records.
+     */
+    async count(input: InferFilters<TSchema>, options?: ISearchOptions<TSchema>): Promise<number> {
+        this.authValidator.validatePermissions((v) =>
+            v.someOf([
+                this.service.getDescriptor('count', '*').toString(),
+                this.service.getDescriptor('read', '*').toString(),
+            ]),
+        )
+        return this.service.count(input, options)
+    }
+}

package/src/domain/events/domain-event.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'bun:test'
+import { DomainEvent } from './domain-event'
+import type { IDomainEventOptions } from './domain-event'
+
+interface Book {
+    title: string
+    author: string
+}
+
+class MyEvent extends DomainEvent<Book> {
+    type = 'BOOK_CREATED' as const
+
+    constructor(options: IDomainEventOptions<Book>) {
+        super(options)
+    }
+}
+
+describe('DomainEvent', () => {
+    it('should create a domain event with default values', () => {
+        const book: Book = { title: '1984', author: 'George Orwell' }
+        const event = new MyEvent({ data: book })
+
+        expect(event.eventId?.length).toBeGreaterThanOrEqual(36) // UUID length
+        expect(event.data).toEqual(book)
+        expect(event.timestamp).toBeInstanceOf(Date)
+        expect(event.type).toBe('BOOK_CREATED')
+        expect(event.session).toBeUndefined() // session is optional and not set by default
+        expect(event.meta).toEqual({}) // meta should default to an empty object
+    })
+
+    it('should create a domain event with metadata', () => {
+        const book: Book = { title: '1984', author: 'George Orwell' }
+        const event = new MyEvent({ data: book, meta: { createdBy: 'user123' } })
+
+        expect(event.meta).toEqual({ createdBy: 'user123' })
+    })
+
+    it('should default timestamp to the current time', () => {
+        const book: Book = { title: '1984', author: 'George Orwell' }
+        const event = new MyEvent({ data: book })
+
+        const now = new Date()
+        expect(event.timestamp.getTime()).toBeLessThanOrEqual(now.getTime())
+        expect(event.timestamp.getTime()).toBeGreaterThanOrEqual(now.getTime() - 1000) // Allow 1 second margin
+    })
+
+    it('should instantiate with no input', () => {
+        const event = new DomainEvent()
+
+        expect(event.eventId).toBeDefined()
+        expect(event.timestamp).toBeInstanceOf(Date)
+        expect(event.type).toBe('UNKNOWN_EVENT')
+        expect(event.data).toBeUndefined()
+        expect(event.meta).toEqual({})
+        expect(event.session).toBeUndefined()
+    })
+
+    it('should create an event with a descriptor but no type', () => {
+        const book: Book = { title: '1984', author: 'George Orwell' }
+        const event = new DomainEvent({
+            data: book,
+            descriptor: { namespace: 'auth', resource: 'user', action: 'create', scope: 'admin' },
+        })
+
+        expect(event.type).toBe('auth::user.create:admin')
+        expect(event.descriptor.namespace).toBe('auth')
+        expect(event.descriptor.resource).toBe('user')
+        expect(event.descriptor.action).toBe('create')
+        expect(event.descriptor.scope).toBe('admin')
+    })
+
+    it('should create an event with a type but no descriptor', () => {
+        const book: Book = { title: '1984', author: 'George Orwell' }
+        const event = new DomainEvent({ data: book, meta: {}, type: 'books::book.create:own' })
+
+        expect(event.type).toBe('books::book.create:own')
+        expect(event.descriptor.namespace).toBe('books')
+        expect(event.descriptor.resource).toBe('book')
+        expect(event.descriptor.action).toBe('create')
+        expect(event.descriptor.scope).toBe('own')
+    })
+})

package/src/domain/events/domain-event.ts

@@ -0,0 +1,69 @@
+import type { IAuthSession } from '@declaro/auth'
+import { type IEvent, type IActionDescriptor, ActionDescriptor, type IActionDescriptorInput } from '@declaro/core'
+import { v4 as uuid } from 'uuid'
+
+export interface IDomainEvent<T, M = any> extends IEvent {
+    eventId: string
+    data?: T
+    meta?: M
+    timestamp: Date
+    descriptor: IActionDescriptor
+    session?: IAuthSession
+}
+
+export interface IDomainEventOptions<TData, TMeta = any> {
+    type?: string
+    eventId?: string
+    data?: TData
+    timestamp?: Date
+    descriptor?: IActionDescriptorInput
+    session?: IAuthSession
+    meta?: TMeta
+}
+
+export interface IDomainEventJSON<T, M = any> {
+    eventId: string
+    data?: T
+    meta?: M
+    timestamp: string // JSON-compatible format
+    type: string
+    session?: { id: string } // Simplified session representation
+}
+
+export class DomainEvent<T, M = any> implements IDomainEvent<T, M> {
+    readonly eventId: string
+    public data?: T
+    public timestamp: Date
+    public type: string = 'UNKNOWN_EVENT'
+    public descriptor: ActionDescriptor
+    public session?: IAuthSession
+    public meta: M
+
+    constructor(options: IDomainEventOptions<T, M> = {}) {
+        if (options.type) {
+            this.type = options.type
+        }
+        this.eventId = options.eventId ?? uuid()
+        this.timestamp = options.timestamp ?? new Date()
+        this.descriptor = options.descriptor
+            ? ActionDescriptor.fromJSON(options.descriptor)
+            : ActionDescriptor.fromString(this.type)
+        if (options.descriptor && this.type === 'UNKNOWN_EVENT') {
+            this.type = this.descriptor.toString()
+        }
+        this.data = options.data
+        this.meta = options.meta ?? ({} as M) // Ensure meta is always defined, defaulting to an empty object
+        this.session = options.session
+    }
+
+    toJSON(): IDomainEventJSON<T, M> {
+        return {
+            eventId: this.eventId,
+            data: this.data,
+            meta: this.meta,
+            timestamp: this.timestamp.toISOString(),
+            type: this.type,
+            session: this.session ? { id: this.session.id } : undefined,
+        }
+    }
+}

package/src/domain/events/event-types.ts

@@ -0,0 +1,21 @@
+export enum ModelQueryEvent {
+    BeforeLoad = 'beforeLoad',
+    AfterLoad = 'afterLoad',
+    BeforeLoadMany = 'beforeLoadMany',
+    AfterLoadMany = 'afterLoadMany',
+    BeforeSearch = 'beforeSearch',
+    AfterSearch = 'afterSearch',
+    BeforeCount = 'beforeCount',
+    AfterCount = 'afterCount',
+}
+
+export enum ModelMutationAction {
+    BeforeCreate = 'beforeCreate',
+    AfterCreate = 'afterCreate',
+    BeforeUpdate = 'beforeUpdate',
+    AfterUpdate = 'afterUpdate',
+    BeforeRemove = 'beforeRemove',
+    AfterRemove = 'afterRemove',
+    BeforeRestore = 'beforeRestore',
+    AfterRestore = 'afterRestore',
+}

package/src/domain/events/mutation-event.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'bun:test'
+import { MutationEvent } from './mutation-event'
+
+describe('MutationEvent', () => {
+    it('should create a mutation event with input and descriptor', () => {
+        const input = { key: 'value' }
+        const descriptor = { namespace: 'test', action: 'create' }
+        const event = new MutationEvent(descriptor, input, {})
+
+        expect(event.descriptor.namespace).toBe('test')
+        expect(event.descriptor.action).toBe('create')
+        expect(event.meta.input).toEqual(input)
+    })
+
+    it('should update meta correctly', () => {
+        const input = { key: 'value' }
+        const descriptor = { namespace: 'test', action: 'create' }
+        const event = new MutationEvent(descriptor, input, {
+            foo: 'bar',
+        })
+
+        event.setMeta({
+            foo: 'baz',
+        })
+
+        expect(event.meta.foo).toBe('baz')
+    })
+
+    it('should set result correctly', () => {
+        const input = { key: 'value' }
+        const descriptor = { namespace: 'test', action: 'create' }
+        const event = new MutationEvent(descriptor, input, {})
+
+        const result = { success: true }
+        event.setResult(result)
+        expect(event.data).toEqual(result)
+    })
+})

package/src/domain/events/mutation-event.ts

@@ -0,0 +1,8 @@
+import type { IActionDescriptorInput } from '@declaro/core'
+import { RequestEvent } from './request-event'
+
+export class MutationEvent<TResult, TInput, TMeta = any> extends RequestEvent<TResult, TInput, TMeta> {
+    constructor(descriptor: IActionDescriptorInput, input: TInput, meta: TMeta = {} as TMeta) {
+        super(descriptor, input, meta)
+    }
+}

package/src/domain/events/query-event.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'bun:test'
+import { QueryEvent } from './query-event'
+
+describe('QueryEvent', () => {
+    describe('load action', () => {
+        it('should lookup a book with the given lookup', () => {
+            const params = { id: 42 }
+            const descriptor = { namespace: 'books', action: 'load' }
+            const query = new QueryEvent(descriptor, params, {})
+
+            expect(query.descriptor.namespace).toBe('books')
+            expect(query.descriptor.action).toBe('load')
+            expect(query.meta.input).toEqual(params)
+        })
+    })
+
+    describe('search action', () => {
+        it('should search for books with the given filters', () => {
+            const params = { text: '1984' }
+            const descriptor = { namespace: 'books', action: 'search' }
+            const query = new QueryEvent(descriptor, params, {})
+
+            expect(query.descriptor.namespace).toBe('books')
+            expect(query.descriptor.action).toBe('search')
+            expect(query.meta.input).toEqual(params)
+        })
+    })
+})

package/src/domain/events/query-event.ts

@@ -0,0 +1,8 @@
+import type { IActionDescriptorInput } from '@declaro/core'
+import { RequestEvent } from './request-event'
+
+export class QueryEvent<TResult, TParams, TMeta = any> extends RequestEvent<TResult, TParams, TMeta> {
+    constructor(descriptor: IActionDescriptorInput, params: TParams, meta: TMeta = {} as TMeta) {
+        super(descriptor, params, meta)
+    }
+}