@declaro/data 2.0.0-beta.12 → 2.0.0-beta.121

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

@@ -0,0 +1,34 @@
+export enum ModelQueryEvent {
+    BeforeLoad = 'beforeLoad',
+    AfterLoad = 'afterLoad',
+    BeforeLoadMany = 'beforeLoadMany',
+    AfterLoadMany = 'afterLoadMany',
+    BeforeSearch = 'beforeSearch',
+    AfterSearch = 'afterSearch',
+    BeforeCount = 'beforeCount',
+    AfterCount = 'afterCount',
+}
+
+export enum ModelMutationAction {
+    Create = 'create',
+    BeforeCreate = 'beforeCreate',
+    AfterCreate = 'afterCreate',
+    Update = 'update',
+    BeforeUpdate = 'beforeUpdate',
+    AfterUpdate = 'afterUpdate',
+    Remove = 'remove',
+    BeforeRemove = 'beforeRemove',
+    AfterRemove = 'afterRemove',
+    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

@@ -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)
+    }
+}

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.meta.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,32 @@
+import type { IActionDescriptorInput, Simplify } from '@declaro/core'
+import { DomainEvent } from './domain-event'
+
+export interface IRequestEventInput<TInput> {
+    input: TInput
+}
+
+export class RequestEvent<TResult, TInput, TMeta = any> extends DomainEvent<
+    TResult,
+    Simplify<IRequestEventInput<TInput> & TMeta>
+> {
+    constructor(descriptor: IActionDescriptorInput, input: TInput, meta: TMeta = {} as TMeta) {
+        super({
+            meta: {
+                ...meta,
+                input,
+            },
+            descriptor,
+        })
+    }
+
+    setMeta(meta: Partial<TMeta>): this {
+        this.meta = { ...this.meta, ...meta }
+        return this
+    }
+
+    setResult(result: TResult): this {
+        this.data = result
+
+        return this
+    }
+}

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>
+}