@declaro/data 2.0.0-beta.14 → 2.0.0-beta.140

package/src/application/model-controller.ts

@@ -0,0 +1,186 @@
+import type { AuthValidator } from '@declaro/auth'
+import { PermissionValidator, type AnyModelSchema } from '@declaro/core'
+import type { ModelService, ICreateOptions, IUpdateOptions } from '../domain/services/model-service'
+import type { ILoadOptions } from '../domain/services/read-only-model-service'
+import type { InferDetail, InferFilters, InferInput, InferLookup, InferSummary } from '../shared/utils/schema-inference'
+import { ReadOnlyModelController } from './read-only-model-controller'
+
+export class ModelController<TSchema extends AnyModelSchema> extends ReadOnlyModelController<TSchema> {
+    constructor(
+        protected readonly service: ModelService<TSchema>,
+        protected readonly authValidator: AuthValidator,
+    ) {
+        super(service, authValidator)
+    }
+
+    async createPermissions(input: InferInput<TSchema>, options?: ICreateOptions): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([
+            this.service.getDescriptor('create', '*').toString(),
+            this.service.getDescriptor('write', '*').toString(),
+        ])
+    }
+
+    async create(input: InferInput<TSchema>, options?: ICreateOptions): Promise<InferDetail<TSchema>> {
+        const permissions = await this.createPermissions(input, options)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.create(input, options)
+    }
+
+    async updatePermissions(
+        lookup: InferLookup<TSchema>,
+        input: InferInput<TSchema>,
+        options?: IUpdateOptions,
+    ): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([
+            this.service.getDescriptor('update', '*').toString(),
+            this.service.getDescriptor('write', '*').toString(),
+        ])
+    }
+
+    async update(
+        lookup: InferLookup<TSchema>,
+        input: InferInput<TSchema>,
+        options?: IUpdateOptions,
+    ): Promise<InferDetail<TSchema>> {
+        const permissions = await this.updatePermissions(lookup, input, options)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.update(lookup, input, options)
+    }
+
+    async removePermissions(lookup: InferLookup<TSchema>, options?: ILoadOptions): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([
+            this.service.getDescriptor('remove', '*').toString(),
+            this.service.getDescriptor('write', '*').toString(),
+        ])
+    }
+
+    async remove(lookup: InferLookup<TSchema>, options?: ILoadOptions): Promise<InferSummary<TSchema>> {
+        const permissions = await this.removePermissions(lookup, options)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.remove(lookup, options)
+    }
+
+    async restorePermissions(lookup: InferLookup<TSchema>, options?: ILoadOptions): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([
+            this.service.getDescriptor('restore', '*').toString(),
+            this.service.getDescriptor('write', '*').toString(),
+        ])
+    }
+
+    async restore(lookup: InferLookup<TSchema>, options?: ILoadOptions): Promise<InferSummary<TSchema>> {
+        const permissions = await this.restorePermissions(lookup, options)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.restore(lookup, options)
+    }
+
+    async upsertPermissions(
+        input: InferInput<TSchema>,
+        options?: ICreateOptions | IUpdateOptions,
+    ): Promise<PermissionValidator> {
+        // Create nested validator for (create AND update) permissions
+        const createAndUpdateValidator = PermissionValidator.create().allOf([
+            this.service.getDescriptor('create', '*').toString(),
+            this.service.getDescriptor('update', '*').toString(),
+        ])
+
+        return PermissionValidator.create().someOf([
+            createAndUpdateValidator,
+            this.service.getDescriptor('write', '*').toString(),
+        ])
+    }
+
+    /**
+     * Upserts a record (creates if it doesn't exist, updates if it does).
+     * @param input The input data for the upsert operation.
+     * @param options Optional create or update options.
+     * @returns The upserted record.
+     */
+    async upsert(input: InferInput<TSchema>, options?: ICreateOptions | IUpdateOptions): Promise<InferDetail<TSchema>> {
+        const permissions = await this.upsertPermissions(input, options)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.upsert(input, options)
+    }
+
+    async bulkUpsertPermissions(
+        inputs: InferInput<TSchema>[],
+        options?: ICreateOptions | IUpdateOptions,
+    ): Promise<PermissionValidator> {
+        // Create nested validator for (create AND update) permissions
+        const createAndUpdateValidator = PermissionValidator.create().allOf([
+            this.service.getDescriptor('create', '*').toString(),
+            this.service.getDescriptor('update', '*').toString(),
+        ])
+
+        return PermissionValidator.create().someOf([
+            createAndUpdateValidator,
+            this.service.getDescriptor('write', '*').toString(),
+        ])
+    }
+
+    /**
+     * Bulk upserts multiple records (creates if they don't exist, updates if they do).
+     * @param inputs Array of input data for the bulk upsert operation.
+     * @param options Optional create or update options.
+     * @returns Array of upserted records.
+     */
+    async bulkUpsert(
+        inputs: InferInput<TSchema>[],
+        options?: ICreateOptions | IUpdateOptions,
+    ): Promise<InferDetail<TSchema>[]> {
+        const permissions = await this.bulkUpsertPermissions(inputs, options)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.bulkUpsert(inputs, options)
+    }
+
+    async permanentlyDeleteFromTrashPermissions(lookup: InferLookup<TSchema>): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([
+            this.service.getDescriptor('permanently-delete-from-trash', '*').toString(),
+            this.service.getDescriptor('permanently-delete', '*').toString(),
+            this.service.getDescriptor('empty-trash', '*').toString(),
+        ])
+    }
+
+    /**
+     * Permanently deletes a specific entity from the trash.
+     * Requires 'permanently-delete-from-trash', 'permanently-delete', or 'empty-trash' permission.
+     * @param lookup The lookup object containing entity identifiers
+     * @returns The permanently deleted entity summary
+     */
+    async permanentlyDeleteFromTrash(lookup: InferLookup<TSchema>): Promise<InferSummary<TSchema>> {
+        const permissions = await this.permanentlyDeleteFromTrashPermissions(lookup)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.permanentlyDeleteFromTrash(lookup)
+    }
+
+    async permanentlyDeletePermissions(lookup: InferLookup<TSchema>): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([this.service.getDescriptor('permanently-delete', '*').toString()])
+    }
+
+    /**
+     * Permanently deletes an entity without moving it to trash first.
+     * Requires 'permanently-delete' permission.
+     * @param lookup The lookup object containing entity identifiers
+     * @returns The permanently deleted entity summary
+     */
+    async permanentlyDelete(lookup: InferLookup<TSchema>): Promise<InferSummary<TSchema>> {
+        const permissions = await this.permanentlyDeletePermissions(lookup)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.permanentlyDelete(lookup)
+    }
+
+    async emptyTrashPermissions(filters?: InferFilters<TSchema>): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([this.service.getDescriptor('empty-trash', '*').toString()])
+    }
+
+    /**
+     * Empties the trash by permanently deleting entities that have been marked as removed.
+     * Requires 'empty-trash' permission.
+     * @param filters Optional filters to apply when selecting entities to delete
+     * @returns The count of entities permanently deleted
+     */
+    async emptyTrash(filters?: InferFilters<TSchema>): Promise<number> {
+        const permissions = await this.emptyTrashPermissions(filters)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.emptyTrash(filters)
+    }
+}

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

@@ -0,0 +1,335 @@
+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'],
+            }),
+            null,
+            authService,
+        )
+        invalidAuthValidator = new AuthValidator(
+            getMockAuthSession({
+                claims: ['authors::author.read:all'],
+            }),
+            null,
+            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'],
+                }),
+                null,
+                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'],
+                }),
+                null,
+                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'],
+                }),
+                null,
+                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'],
+                }),
+                null,
+                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
+                }),
+                null,
+                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
+                }),
+                null,
+                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,79 @@
+import type { AuthValidator } from '@declaro/auth'
+import {} from '@declaro/auth'
+import { PermissionValidator, 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 loadPermissions(lookup: InferLookup<TSchema>): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([
+            this.service.getDescriptor('load', '*').toString(),
+            this.service.getDescriptor('read', '*').toString(),
+        ])
+    }
+
+    async load(lookup: InferLookup<TSchema>, options?: ILoadOptions): Promise<InferDetail<TSchema>> {
+        const permissions = await this.loadPermissions(lookup)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.load(lookup, options)
+    }
+
+    async loadManyPermissions(lookups: InferLookup<TSchema>[]): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([
+            this.service.getDescriptor('loadMany', '*').toString(),
+            this.service.getDescriptor('read', '*').toString(),
+        ])
+    }
+
+    async loadMany(lookups: InferLookup<TSchema>[], options?: ILoadOptions): Promise<InferDetail<TSchema>[]> {
+        const permissions = await this.loadManyPermissions(lookups)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.loadMany(lookups, options)
+    }
+
+    async searchPermissions(
+        input: InferFilters<TSchema>,
+        options?: ISearchOptions<TSchema>,
+    ): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([
+            this.service.getDescriptor('search', '*').toString(),
+            this.service.getDescriptor('read', '*').toString(),
+        ])
+    }
+
+    async search(
+        input: InferFilters<TSchema>,
+        options?: ISearchOptions<TSchema>,
+    ): Promise<InferSearchResults<TSchema>> {
+        const permissions = await this.searchPermissions(input, options)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        return this.service.search(input, options)
+    }
+
+    async countPermissions(
+        input: InferFilters<TSchema>,
+        options?: ISearchOptions<TSchema>,
+    ): Promise<PermissionValidator> {
+        return PermissionValidator.create().someOf([
+            this.service.getDescriptor('count', '*').toString(),
+            this.service.getDescriptor('read', '*').toString(),
+        ])
+    }
+
+    /**
+     * 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> {
+        const permissions = await this.countPermissions(input, options)
+        this.authValidator.validatePermissions((v) => v.extend(permissions))
+        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')
+    })
+})