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

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

@@ -0,0 +1,228 @@
+import { describe, it, expect } from 'bun:test'
+import { QueryEvent } from './query-event'
+import { ActionDescriptor, type IActionDescriptorInput } from '@declaro/core'
+
+interface IBookResult {
+    id: string
+    title: string
+    description: string
+    author: string
+    year: number
+}
+
+interface ILoadParams {
+    id: string
+}
+
+interface ISearchParams {
+    text?: string
+    author?: string
+    year?: number
+}
+
+interface ICustomMeta {
+    customField?: string
+    anotherField?: number
+}
+
+describe('QueryEvent', () => {
+    it('should create a query event with params and descriptor', () => {
+        const params: ILoadParams = { id: '1' }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'load' }
+        const event = new QueryEvent<IBookResult, ILoadParams>(descriptor, params)
+
+        expect(event.input).toEqual(params)
+        expect(event.descriptor.toString()).toEqual(new ActionDescriptor(descriptor).toString())
+        expect(event.meta).toEqual({})
+        expect(event.data).toBeUndefined()
+    })
+
+    it('should set result correctly', () => {
+        const params: ILoadParams = { id: '1' }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'load' }
+        const event = new QueryEvent<IBookResult, ILoadParams>(descriptor, params)
+
+        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 update meta correctly', () => {
+        const params: ISearchParams = { text: '1984' }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'search' }
+        const event = new QueryEvent<IBookResult[], ISearchParams, ICustomMeta>(descriptor, params)
+
+        event.setMeta({ customField: 'custom value' })
+
+        expect(event.meta.customField).toBe('custom value')
+    })
+
+    it('should serialize to JSON with eventId and timestamp', () => {
+        const params: ILoadParams = { id: '1' }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'load' }
+        const event = new QueryEvent<IBookResult, ILoadParams>(descriptor, params)
+
+        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.load')
+        expect(json.input).toEqual(params)
+        expect(json.data).toEqual(result)
+    })
+
+    it('should handle chaining of setter methods', () => {
+        const params: ILoadParams = { id: '1' }
+        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: 'load' }
+        const event = new QueryEvent<IBookResult, ILoadParams, ICustomMeta>(descriptor, params)
+            .setMeta({ customField: 'value' })
+            .setResult(result)
+
+        expect(event.input).toEqual(params)
+        expect(event.meta.customField).toBe('value')
+        expect(event.data).toEqual(result)
+    })
+
+    it('should update input after initialization', () => {
+        const params: ISearchParams = { text: '1984' }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'search' }
+        const event = new QueryEvent<IBookResult[], ISearchParams>(descriptor, params)
+
+        const newParams: ISearchParams = {
+            text: 'Brave New World',
+            author: 'Aldous Huxley',
+        }
+        event.setInput(newParams)
+
+        expect(event.input).toEqual(newParams)
+    })
+
+    it('should maintain type throughout lifecycle', () => {
+        const params: ILoadParams = { id: '1' }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'load' }
+        const event = new QueryEvent<IBookResult, ILoadParams>(descriptor, params)
+
+        expect(event.type).toBe('books::book.load')
+
+        event.setInput({ id: '2' })
+        expect(event.type).toBe('books::book.load')
+
+        const result: IBookResult = {
+            id: '2',
+            title: 'Another Book',
+            description: 'Another description',
+            author: 'Another Author',
+            year: 2025,
+        }
+        event.setResult(result)
+        expect(event.type).toBe('books::book.load')
+    })
+
+    it('should handle search action with multiple filters', () => {
+        const params: ISearchParams = {
+            text: 'science fiction',
+            author: 'Isaac Asimov',
+            year: 1950,
+        }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'search' }
+        const event = new QueryEvent<IBookResult[], ISearchParams>(descriptor, params)
+
+        expect(event.descriptor.action).toBe('search')
+        expect(event.input).toEqual(params)
+    })
+
+    it('should handle search results as array', () => {
+        const params: ISearchParams = { text: 'Foundation' }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'search' }
+        const event = new QueryEvent<IBookResult[], ISearchParams>(descriptor, params)
+
+        const results: IBookResult[] = [
+            {
+                id: '1',
+                title: 'Foundation',
+                description: 'First book',
+                author: 'Isaac Asimov',
+                year: 1951,
+            },
+            {
+                id: '2',
+                title: 'Foundation and Empire',
+                description: 'Second book',
+                author: 'Isaac Asimov',
+                year: 1952,
+            },
+        ]
+        event.setResult(results)
+
+        expect(event.data).toEqual(results)
+        expect(event.data?.length).toBe(2)
+    })
+
+    it('should handle load action with single result', () => {
+        const params: ILoadParams = { id: '42' }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'load' }
+        const event = new QueryEvent<IBookResult, ILoadParams>(descriptor, params)
+
+        const result: IBookResult = {
+            id: '42',
+            title: "The Hitchhiker's Guide to the Galaxy",
+            description: "Don't Panic",
+            author: 'Douglas Adams',
+            year: 1979,
+        }
+        event.setResult(result)
+
+        expect(event.data).toEqual(result)
+        expect(event.descriptor.action).toBe('load')
+    })
+
+    it('should serialize meta to JSON', () => {
+        const params: ISearchParams = { text: 'test' }
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'search' }
+        const event = new QueryEvent<IBookResult[], ISearchParams, ICustomMeta>(descriptor, params, {
+            customField: 'custom value',
+            anotherField: 123,
+        })
+
+        const json = event.toJSON()
+
+        expect(json.meta.customField).toBe('custom value')
+        expect(json.meta.anotherField).toBe(123)
+        expect(json.input).toEqual(params)
+    })
+
+    it('should handle empty search params', () => {
+        const params: ISearchParams = {}
+        const descriptor: IActionDescriptorInput = { namespace: 'books', resource: 'book', action: 'search' }
+        const event = new QueryEvent<IBookResult[], ISearchParams>(descriptor, params)
+
+        expect(event.input).toEqual({})
+        expect(event.descriptor.action).toBe('search')
+    })
+})

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

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

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

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

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

@@ -0,0 +1,47 @@
+import type { IActionDescriptorInput, Simplify } from '@declaro/core'
+import { DomainEvent } from './domain-event'
+
+export interface IRequestEventMeta {}
+
+export interface IRequestEventJSON<TInput, TMeta = IRequestEventMeta> extends Simplify<DomainEvent<TInput, TMeta>> {
+    input: TInput
+}
+
+export class RequestEvent<TResult, TInput, TMeta extends IRequestEventMeta = IRequestEventMeta> extends DomainEvent<
+    TResult,
+    TMeta
+> {
+    input: TInput
+
+    constructor(descriptor: IActionDescriptorInput, input: TInput, meta: TMeta = {} as TMeta) {
+        super({
+            meta,
+            descriptor,
+        })
+
+        this.input = input
+    }
+
+    setInput(input: TInput): this {
+        this.input = input
+        return this
+    }
+
+    setMeta(meta: Partial<TMeta>): this {
+        this.meta = { ...this.meta, ...meta }
+        return this
+    }
+
+    setResult(result: TResult): this {
+        this.data = result
+
+        return this
+    }
+
+    toJSON() {
+        return {
+            ...super.toJSON(),
+            input: this.input,
+        }
+    }
+}

package/src/domain/interfaces/repository.ts

@@ -0,0 +1,136 @@
+import type { AnyModelSchema } from '@declaro/core'
+import type {
+    InferDetail,
+    InferFilters,
+    InferInput,
+    InferLookup,
+    InferSearchResults,
+    InferSummary,
+} from '../../shared/utils/schema-inference'
+import type { ICreateOptions, IUpdateOptions } from '../services/model-service'
+import type { ILoadOptions, ISearchOptions } from '../services/read-only-model-service'
+
+export interface IRepository<TSchema extends AnyModelSchema> {
+    /**
+     * Loads a single element based on the provided lookup.
+     *
+     * @param input - The lookup criteria for the element.
+     * @returns A promise resolving to the detailed element or null if not found.
+     */
+    load(input: InferLookup<TSchema>, options?: ILoadOptions): Promise<InferDetail<TSchema> | null>
+
+    /**
+     * Loads multiple elements based on the provided lookups.
+     *
+     * @param inputs - The lookup criteria for the elements.
+     * @returns A promise resolving to an array of detailed elements.
+     */
+    loadMany(inputs: InferLookup<TSchema>[], options?: ILoadOptions): Promise<InferDetail<TSchema>[]>
+
+    /**
+     * Searches for elements based on filters and optional pagination.
+     *
+     * @param input - The filters to apply to the search.
+     * @param pagination - Optional pagination criteria.
+     * @returns A promise resolving to the search results.
+     */
+    search(input: InferFilters<TSchema>, options?: ISearchOptions<TSchema>): Promise<InferSearchResults<TSchema>>
+
+    /**
+     * Deletes elements based on the provided lookups.
+     *
+     * @param lookup - The lookup criteria for the element to delete.
+     * @returns A promise resolving to the deleted list item.
+     */
+    remove(lookup: InferLookup<TSchema>, options?: ILoadOptions): Promise<InferSummary<TSchema>>
+
+    /**
+     * Restores an element based on the provided lookups, if a soft-deleted copy exists.
+     *
+     * @param lookup - The lookup criteria for the element to restore.
+     * @returns A promise resolving to the restored list item.
+     */
+    restore(lookup: InferLookup<TSchema>, options?: ILoadOptions): Promise<InferSummary<TSchema>>
+
+    /**
+     * Creates a new element based on the provided input.
+     *
+     * @param input - The input data for the new element.
+     * @returns A promise resolving to the detailed created element.
+     */
+    create(input: InferInput<TSchema>, options?: ICreateOptions): Promise<InferDetail<TSchema>>
+
+    /**
+     * Updates elements based on filters.
+     *
+     * @param filters - The filters to apply to the update.
+     * @returns A promise resolving to the detailed updated element.
+     */
+    update(
+        lookup: InferLookup<TSchema>,
+        input: InferInput<TSchema>,
+        options?: IUpdateOptions,
+    ): Promise<InferDetail<TSchema>>
+
+    /**
+     * Upserts an element based on the provided input.
+     * If the element exists, it will be updated; otherwise, a new element will be created.
+     *
+     * A load operation will be performed to check if the element exists. create/update related events will be dispatched accordingly.
+     *
+     * @param input - The input data for the new or existing element.
+     * @returns A promise resolving to the detailed created or updated element.
+     */
+    upsert(input: InferInput<TSchema>, options?: ICreateOptions | IUpdateOptions): Promise<InferDetail<TSchema>>
+
+    /**
+     * Upserts multiple elements based on the provided inputs.
+     * If an element exists, it will be updated; otherwise, a new element will be created.
+     *
+     * A loadMany operation will be performed to check if the elements exist. create/update related events will be dispatched accordingly.
+     *
+     * @param inputs - The input data for the upsert operation.
+     * @returns A promise resolving to an array of detailed upserted elements.
+     */
+    bulkUpsert(
+        inputs: InferInput<TSchema>[],
+        options?: ICreateOptions | IUpdateOptions,
+    ): Promise<InferDetail<TSchema>[]>
+
+    /**
+     * Counts the number of elements matching the provided search criteria.
+     *
+     * @param search - The search criteria to apply.
+     * @returns A promise resolving to the count of matching elements.
+     */
+    count(search: InferFilters<TSchema>, options?: ISearchOptions<TSchema>): Promise<number>
+
+    /**
+     * Permanently deletes all items from trash, optionally filtered by the provided criteria.
+     * Items deleted via this method cannot be restored.
+     *
+     * @param filters - Optional filters to apply when selecting items to delete from trash.
+     * @returns A promise resolving to the count of permanently deleted items.
+     */
+    emptyTrash(filters?: InferFilters<TSchema>): Promise<number>
+
+    /**
+     * Permanently deletes a specific item from trash based on the provided lookup.
+     * The item must exist in trash (previously removed). Items deleted via this method cannot be restored.
+     *
+     * @param lookup - The lookup criteria for the item to permanently delete from trash.
+     * @returns A promise resolving to the permanently deleted item summary.
+     * @throws Error if the item is not found in trash.
+     */
+    permanentlyDeleteFromTrash(lookup: InferLookup<TSchema>): Promise<InferSummary<TSchema>>
+
+    /**
+     * Permanently deletes an item based on the provided lookup, regardless of whether it is active or in trash.
+     * Items deleted via this method cannot be restored.
+     *
+     * @param lookup - The lookup criteria for the item to permanently delete.
+     * @returns A promise resolving to the permanently deleted item summary.
+     * @throws Error if the item is not found in either active data or trash.
+     */
+    permanentlyDelete(lookup: InferLookup<TSchema>): Promise<InferSummary<TSchema>>
+}

package/src/domain/models/pagination.ts

@@ -0,0 +1,28 @@
+import z from 'zod/v4'
+import { ZodModel } from '@declaro/zod'
+import { ModelSchema } from '@declaro/core'
+
+export const PaginationInput = new ZodModel(
+    'PaginationInput' as const,
+    z.object({
+        page: z.number().int().min(1).default(1).nullish(),
+        pageSize: z.number().int().min(1).default(25).nullish(),
+    }),
+)
+export type IPaginationInput = z.infer<typeof PaginationInput.schema>
+
+export const PaginationOutput = new ZodModel(
+    'PaginationOutput' as const,
+    z.object({
+        page: z.number().int().min(1).default(1),
+        pageSize: z.number().int().min(1).default(25),
+        total: z.number().int().min(0).default(0),
+        totalPages: z.number().int().min(1).default(1),
+    }),
+)
+export type IPagination = z.infer<typeof PaginationOutput.schema>
+
+export const PaginationSchema = ModelSchema.create('Pagination').custom({
+    input: () => PaginationInput,
+    output: () => PaginationOutput,
+})

package/src/domain/services/base-model-service.ts

@@ -0,0 +1,54 @@
+import { ActionDescriptor, type AnyModelSchema, type ModelSchema } from '@declaro/core'
+import type { IModelServiceArgs } from './model-service-args'
+import type { IRepository } from '../interfaces/repository'
+import type {
+    InferEntityMetadata,
+    InferInput,
+    InferLookup,
+    InferPrimaryKeyType,
+} from '../../shared/utils/schema-inference'
+
+export interface IActionOptions {
+    /**
+     * The scope of the load operation, e.g., 'detail', 'list', etc.
+     */
+    scope?: string
+}
+
+export class BaseModelService<TSchema extends AnyModelSchema> {
+    protected readonly namespace: string
+    protected readonly schema: TSchema
+    protected readonly entityMetadata: InferEntityMetadata<TSchema>
+    protected readonly emitter: IModelServiceArgs<TSchema>['emitter']
+    protected readonly repository: IRepository<TSchema>
+
+    constructor(args: IModelServiceArgs<TSchema>) {
+        this.schema = args.schema
+        this.namespace = args.namespace ?? 'global'
+        this.emitter = args.emitter
+        this.repository = args.repository
+        this.entityMetadata = this.schema.getEntityMetadata()
+    }
+
+    getDescriptor(action: string, scope?: string) {
+        return ActionDescriptor.fromJSON({
+            namespace: this.namespace,
+            resource: this.schema.name,
+            action,
+            scope,
+        })
+    }
+
+    getPrimaryKeyValue(input: InferLookup<TSchema>): InferPrimaryKeyType<TSchema>
+    getPrimaryKeyValue(input: InferInput<TSchema>): InferPrimaryKeyType<TSchema>
+    getPrimaryKeyValue(input: any = {}): InferPrimaryKeyType<TSchema> {
+        if (!this.entityMetadata?.primaryKey) {
+            return undefined
+        }
+        return input[this.entityMetadata.primaryKey]
+    }
+
+    public getSchema() {
+        return this.schema
+    }
+}

package/src/domain/services/model-service-args.ts

@@ -0,0 +1,9 @@
+import type { AnyModelSchema, EventManager } from '@declaro/core'
+import type { IRepository } from '../interfaces/repository'
+
+export interface IModelServiceArgs<TSchema extends AnyModelSchema> {
+    schema: TSchema
+    namespace?: string
+    emitter: EventManager
+    repository: IRepository<TSchema>
+}