@declaro/data 2.0.0-beta.120 → 2.0.0-beta.125

package/src/application/model-controller.ts

@@ -1,7 +1,7 @@
 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 { InferDetail, InferInput, InferLookup, InferSummary } from '../shared/utils/schema-inference'
+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> {
@@ -89,4 +89,47 @@ export class ModelController<TSchema extends AnyModelSchema> extends ReadOnlyMod
         )
         return this.service.bulkUpsert(inputs, options)
     }
+
+    /**
+     * 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>> {
+        this.authValidator.validatePermissions((v) =>
+            v.someOf([
+                this.service.getDescriptor('permanently-delete-from-trash', '*').toString(),
+                this.service.getDescriptor('permanently-delete', '*').toString(),
+                this.service.getDescriptor('empty-trash', '*').toString(),
+            ]),
+        )
+        return this.service.permanentlyDeleteFromTrash(lookup)
+    }
+
+    /**
+     * 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>> {
+        this.authValidator.validatePermissions((v) =>
+            v.someOf([this.service.getDescriptor('permanently-delete', '*').toString()]),
+        )
+        return this.service.permanentlyDelete(lookup)
+    }
+
+    /**
+     * 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> {
+        this.authValidator.validatePermissions((v) =>
+            v.someOf([this.service.getDescriptor('empty-trash', '*').toString()]),
+        )
+        return this.service.emptyTrash(filters)
+    }
 }

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

@@ -24,7 +24,7 @@ export interface IDomainEventOptions<TData, TMeta = any> {
 export interface IDomainEventJSON<T, M = any> {
     eventId: string
     data?: T
-    meta?: M
+    meta: M
     timestamp: string // JSON-compatible format
     type: string
     session?: { id: string } // Simplified session representation

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

@@ -22,4 +22,13 @@ export enum ModelMutationAction {
     Restore = 'restore',
     BeforeRestore = 'beforeRestore',
     AfterRestore = 'afterRestore',
+    EmptyTrash = 'emptyTrash',
+    BeforeEmptyTrash = 'beforeEmptyTrash',
+    AfterEmptyTrash = 'afterEmptyTrash',
+    PermanentlyDeleteFromTrash = 'permanentlyDeleteFromTrash',
+    BeforePermanentlyDeleteFromTrash = 'beforePermanentlyDeleteFromTrash',
+    AfterPermanentlyDeleteFromTrash = 'afterPermanentlyDeleteFromTrash',
+    PermanentlyDelete = 'permanentlyDelete',
+    BeforePermanentlyDelete = 'beforePermanentlyDelete',
+    AfterPermanentlyDelete = 'afterPermanentlyDelete',
 }

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

@@ -1,38 +1,390 @@
 import { describe, it, expect } from 'bun:test'
 import { MutationEvent } from './mutation-event'
+import { ActionDescriptor, type IActionDescriptorInput } from '@declaro/core'
+
+interface IBookResult {
+    id: string
+    title: string
+    description: string
+    author: string
+    year: number
+}
+
+interface IBookInput {
+    title: string
+    description: string
+    author: string
+    year: number
+}
 
 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, {})
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'create' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
 
-        expect(event.descriptor.namespace).toBe('test')
-        expect(event.descriptor.action).toBe('create')
-        expect(event.meta.input).toEqual(input)
+        expect(event.input).toEqual(input)
+        expect(event.descriptor.toString()).toEqual(new ActionDescriptor(descriptor).toString())
+        expect(event.meta).toEqual({})
+        expect(event.data).toBeUndefined()
     })
 
-    it('should update meta correctly', () => {
-        const input = { key: 'value' }
-        const descriptor = { namespace: 'test', action: 'create' }
-        const event = new MutationEvent(descriptor, input, {
-            foo: 'bar',
+    it('should allow setting existing result in meta', () => {
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const existing: IBookResult = {
+            id: '1',
+            title: 'Old Title',
+            description: 'Old Description',
+            author: 'Old Author',
+            year: 2000,
+        }
+
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'update' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input, {
+            existing,
         })
 
+        expect(event.input).toEqual(input)
+        expect(event.meta.existing).toEqual(existing)
+    })
+
+    it('should update meta correctly', () => {
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'create' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+
+        const existing: IBookResult = {
+            id: '1',
+            title: 'Old Title',
+            description: 'Old Description',
+            author: 'Old Author',
+            year: 2000,
+        }
+
         event.setMeta({
-            foo: 'baz',
+            existing,
         })
 
-        expect(event.meta.foo).toBe('baz')
+        expect(event.meta.existing).toEqual(existing)
     })
 
     it('should set result correctly', () => {
-        const input = { key: 'value' }
-        const descriptor = { namespace: 'test', action: 'create' }
-        const event = new MutationEvent(descriptor, input, {})
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'create' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+
+        expect(event.data).toBeUndefined()
+
+        const result: IBookResult = {
+            id: '1',
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        event.setResult(result)
+
+        expect(event.data).toEqual(result)
+    })
+
+    it('should serialize to JSON with eventId and timestamp', () => {
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'create' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+
+        const result: IBookResult = {
+            id: '1',
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        event.setResult(result)
+
+        const json = event.toJSON()
+
+        expect(json.eventId).toBeDefined()
+        expect(json.timestamp).toBeDefined()
+        expect(json.type).toBe('books::book.create')
+        expect(json.input).toEqual(input)
+        expect(json.data).toEqual(result)
+    })
+
+    it('should handle chaining of setter methods', () => {
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const existing: IBookResult = {
+            id: '1',
+            title: 'Old Title',
+            description: 'Old Description',
+            author: 'Old Author',
+            year: 2000,
+        }
+        const result: IBookResult = {
+            id: '1',
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'update' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+            .setMeta({ existing })
+            .setResult(result)
+
+        expect(event.input).toEqual(input)
+        expect(event.meta.existing).toEqual(existing)
+        expect(event.data).toEqual(result)
+    })
+
+    it('should update input after initialization', () => {
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'create' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+
+        const newInput: IBookInput = {
+            title: 'Updated Book',
+            description: 'Updated description',
+            author: 'New Author',
+            year: 2025,
+        }
+        event.setInput(newInput)
+
+        expect(event.input).toEqual(newInput)
+    })
+
+    it('should allow setting input multiple times', () => {
+        const input: IBookInput = {
+            title: 'First Book',
+            description: 'First description',
+            author: 'First Author',
+            year: 2024,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'create' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+
+        const secondInput: IBookInput = {
+            title: 'Second Book',
+            description: 'Second description',
+            author: 'Second Author',
+            year: 2025,
+        }
+        event.setInput(secondInput)
+        expect(event.input).toEqual(secondInput)
 
-        const result = { success: true }
+        const thirdInput: IBookInput = {
+            title: 'Third Book',
+            description: 'Third description',
+            author: 'Third Author',
+            year: 2026,
+        }
+        event.setInput(thirdInput)
+        expect(event.input).toEqual(thirdInput)
+    })
+
+    it('should return this from setInput for chaining', () => {
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'create' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+
+        const newInput: IBookInput = {
+            title: 'Updated Book',
+            description: 'Updated description',
+            author: 'New Author',
+            year: 2025,
+        }
+        const result: IBookResult = {
+            id: '1',
+            ...newInput,
+        }
+
+        const returned = event.setInput(newInput).setResult(result)
+
+        expect(returned).toBe(event)
+        expect(event.input).toEqual(newInput)
+        expect(event.data).toEqual(result)
+    })
+
+    it('should replace entire input object when using setInput', () => {
+        const input: IBookInput = {
+            title: 'Original Book',
+            description: 'Original description',
+            author: 'Original Author',
+            year: 2024,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'update' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+
+        expect(event.input.title).toBe('Original Book')
+
+        const partialInput: IBookInput = {
+            title: 'New Title',
+            description: 'New description',
+            author: 'New Author',
+            year: 2025,
+        }
+        event.setInput(partialInput)
+
+        expect(event.input).toEqual(partialInput)
+        expect(event.input.title).toBe('New Title')
+        expect(event.input.year).toBe(2025)
+    })
+
+    it('should update existing in meta', () => {
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const existing: IBookResult = {
+            id: '1',
+            title: 'Old Title',
+            description: 'Old Description',
+            author: 'Old Author',
+            year: 2000,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'update' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input, { existing })
+
+        const newExisting: IBookResult = {
+            id: '1',
+            title: 'Different Title',
+            description: 'Different Description',
+            author: 'Different Author',
+            year: 2010,
+        }
+        event.setMeta({ existing: newExisting })
+
+        expect(event.meta.existing).toEqual(newExisting)
+    })
+
+    it('should handle delete action with existing record', () => {
+        const input = { id: '1' }
+        const existing: IBookResult = {
+            id: '1',
+            title: 'Book to Delete',
+            description: 'This will be deleted',
+            author: 'Some Author',
+            year: 2020,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'delete' }
+        const event = new MutationEvent<IBookResult, { id: string }>(descriptor, input, { existing })
+
+        expect(event.descriptor.action).toBe('delete')
+        expect(event.meta.existing).toEqual(existing)
+        expect(event.input).toEqual(input)
+    })
+
+    it('should maintain type throughout lifecycle', () => {
+        const input: IBookInput = {
+            title: 'Test Book',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'create' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+
+        expect(event.type).toBe('books::book.create')
+
+        event.setInput({ ...input, title: 'Updated' })
+        expect(event.type).toBe('books::book.create')
+
+        const result: IBookResult = {
+            id: '1',
+            title: 'Updated',
+            description: 'A book for testing',
+            author: 'Author Name',
+            year: 2024,
+        }
         event.setResult(result)
+        expect(event.type).toBe('books::book.create')
+    })
+
+    it('should serialize existing to JSON for update action', () => {
+        const input: IBookInput = {
+            title: 'Updated Title',
+            description: 'Updated description',
+            author: 'Author Name',
+            year: 2024,
+        }
+        const existing: IBookResult = {
+            id: '1',
+            title: 'Old Title',
+            description: 'Old Description',
+            author: 'Old Author',
+            year: 2020,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'update' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input, { existing })
+
+        const json = event.toJSON()
+
+        expect(json.meta.existing).toEqual(existing)
+        expect(json.input).toEqual(input)
+    })
+
+    it('should handle create action without existing', () => {
+        const input: IBookInput = {
+            title: 'New Book',
+            description: 'Brand new',
+            author: 'New Author',
+            year: 2024,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'create' }
+        const event = new MutationEvent<IBookResult, IBookInput>(descriptor, input)
+
+        expect(event.meta.existing).toBeUndefined()
+        expect(event.descriptor.action).toBe('create')
+
+        const result: IBookResult = {
+            id: '1',
+            ...input,
+        }
+        event.setResult(result)
+
         expect(event.data).toEqual(result)
     })
 })

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

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