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

package/src/domain/services/read-only-model-service.ts

@@ -0,0 +1,211 @@
+import type { AnyModelSchema, Model } from '@declaro/core'
+import type {
+    InferDetail,
+    InferFilters,
+    InferLookup,
+    InferSearchResults,
+    InferSort,
+    InferSummary,
+} from '../../shared/utils/schema-inference'
+import { ModelQueryEvent } from '../events/event-types'
+import { QueryEvent } from '../events/query-event'
+import { BaseModelService, type IActionOptions } from './base-model-service'
+import type { IPaginationInput } from '../models/pagination'
+
+/**
+ * Options for loading records.
+ */
+export interface ILoadOptions extends IActionOptions {
+    /**
+     * If true, only removed (soft-deleted) records will be returned.
+     */
+    removedOnly?: boolean
+    /**
+     * If true, both removed and non-removed records will be returned.
+     */
+    includeRemoved?: boolean
+
+    /**
+     * If true, skips dispatching events for this action.
+     */
+    doNotDispatchEvents?: boolean
+
+    /**
+     * If true, bypasses any caching mechanism and forces fresh data retrieval from the repository.
+     *
+     * Use with caution, as this may have performance implications. This option is typically used in scenarios where data consistency is critical and the latest data must be retrieved, such as after a known update or in real-time applications.
+     */
+    noCache?: boolean
+}
+export interface ISearchOptions<TSchema extends AnyModelSchema> extends IActionOptions {
+    pagination?: IPaginationInput
+    sort?: InferSort<TSchema>
+    /**
+     * If true, only removed (soft-deleted) records will be returned.
+     */
+    removedOnly?: boolean
+    /**
+     * If true, both removed and non-removed records will be returned.
+     */
+    includeRemoved?: boolean
+    /**
+     * If true, skips dispatching events for this action.
+     */
+    doNotDispatchEvents?: boolean
+}
+
+export class ReadOnlyModelService<TSchema extends AnyModelSchema> extends BaseModelService<TSchema> {
+    /**
+     * Normalize the detail data to match the expected schema.
+     * WARNING: This method is called once per detail in load operations.
+     * Any intensive operations or queries should be avoided here, and done via bulk operations in the respective methods such as `loadMany` instead.
+     * @param detail The detail data to normalize.
+     * @returns The normalized detail data.
+     */
+    async normalizeDetail(detail: InferDetail<TSchema>): Promise<InferDetail<TSchema>> {
+        return detail
+    }
+
+    /**
+     * Normalize the summary data to match the expected schema.
+     * WARNING: This method is called once per summary in search results, often in parallel.
+     * Any intensive operations or queries should be avoided here, and done via bulk operations in the respective methods such as `search` instead.
+     *
+     * @param summary The summary data to normalize.
+     * @returns The normalized summary data.
+     */
+    async normalizeSummary(summary: InferSummary<TSchema>): Promise<InferSummary<TSchema>> {
+        return summary
+    }
+
+    /**
+     * Load a single record by its lookup criteria.
+     * @param lookup The lookup criteria to find the record.
+     * @param options Additional options for the load operation.
+     * @returns The loaded record details.
+     */
+    async load(lookup: InferLookup<TSchema>, options?: ILoadOptions): Promise<InferDetail<TSchema>> {
+        // Emit the before load event
+        if (!options?.doNotDispatchEvents) {
+            const beforeLoadEvent = new QueryEvent<InferDetail<TSchema>, InferLookup<TSchema>>(
+                this.getDescriptor(ModelQueryEvent.BeforeLoad, options?.scope),
+                lookup,
+            )
+            await this.emitter.emitAsync(beforeLoadEvent)
+        }
+
+        // Load the details from the repository
+        const details = await this.repository.load(lookup, options)
+
+        // Emit the after load event
+        if (!options?.doNotDispatchEvents) {
+            const afterLoadEvent = new QueryEvent<InferDetail<TSchema>, InferLookup<TSchema>>(
+                this.getDescriptor(ModelQueryEvent.AfterLoad, options?.scope),
+                lookup,
+            ).setResult(details)
+            await this.emitter.emitAsync(afterLoadEvent)
+        }
+
+        return await this.normalizeDetail(details)
+    }
+
+    /**
+     * Load multiple records by their lookup criteria.
+     * @param lookups The lookup criteria to find the records.
+     * @param options Additional options for the load operation.
+     * @returns An array of loaded record details.
+     */
+    async loadMany(lookups: InferLookup<TSchema>[], options?: ILoadOptions): Promise<InferDetail<TSchema>[]> {
+        // Emit the before load many event
+        if (!options?.doNotDispatchEvents) {
+            const beforeLoadManyEvent = new QueryEvent<InferDetail<TSchema>[], InferLookup<TSchema>[]>(
+                this.getDescriptor(ModelQueryEvent.BeforeLoadMany, options?.scope),
+                lookups,
+            )
+            await this.emitter.emitAsync(beforeLoadManyEvent)
+        }
+
+        // Load the details from the repository
+        const details = await this.repository.loadMany(lookups, options)
+
+        // Emit the after load many event
+        if (!options?.doNotDispatchEvents) {
+            const afterLoadManyEvent = new QueryEvent<InferDetail<TSchema>[], InferLookup<TSchema>[]>(
+                this.getDescriptor(ModelQueryEvent.AfterLoadMany, options?.scope),
+                lookups,
+            ).setResult(details)
+            await this.emitter.emitAsync(afterLoadManyEvent)
+        }
+
+        return await Promise.all(details.map((detail) => this.normalizeDetail(detail)))
+    }
+
+    /**
+     * Search for records matching the given filters.
+     * @param filters The filters to apply to the search.
+     * @param options Additional options for the search operation.
+     * @returns The search results.
+     */
+    async search(
+        filters: InferFilters<TSchema>,
+        options?: ISearchOptions<TSchema>,
+    ): Promise<InferSearchResults<TSchema>> {
+        // Emit the before search event
+        if (!options?.doNotDispatchEvents) {
+            const beforeSearchEvent = new QueryEvent<InferSearchResults<TSchema>, InferFilters<TSchema>>(
+                this.getDescriptor(ModelQueryEvent.BeforeSearch, options?.scope),
+                filters,
+            )
+            await this.emitter.emitAsync(beforeSearchEvent)
+        }
+
+        // Search the repository with the provided filters
+        const results = await this.repository.search(filters, options)
+
+        // Emit the after search event
+        if (!options?.doNotDispatchEvents) {
+            const afterSearchEvent = new QueryEvent<InferSearchResults<TSchema>, InferFilters<TSchema>>(
+                this.getDescriptor(ModelQueryEvent.AfterSearch, options?.scope),
+                filters,
+            ).setResult(results)
+            await this.emitter.emitAsync(afterSearchEvent)
+        }
+
+        // Return the search results
+        return {
+            ...results,
+            results: await Promise.all(results.results.map((summary) => this.normalizeSummary(summary))),
+        }
+    }
+
+    /**
+     * Count the number of records matching the given filters.
+     * @param filters The filters to apply to the count operation.
+     * @returns The count of matching records.
+     */
+    async count(filters: InferFilters<TSchema>, options?: ISearchOptions<TSchema>): Promise<number> {
+        // Emit the before count event
+        if (!options?.doNotDispatchEvents) {
+            const beforeCountEvent = new QueryEvent<number, InferFilters<TSchema>>(
+                this.getDescriptor(ModelQueryEvent.BeforeCount, options?.scope),
+                filters,
+            )
+            await this.emitter.emitAsync(beforeCountEvent)
+        }
+
+        // Count the records in the repository
+        const count = await this.repository.count(filters, options)
+
+        // Emit the after count event
+        if (!options?.doNotDispatchEvents) {
+            const afterCountEvent = new QueryEvent<number, InferFilters<TSchema>>(
+                this.getDescriptor(ModelQueryEvent.AfterCount, options?.scope),
+                filters,
+            ).setResult(count)
+            await this.emitter.emitAsync(afterCountEvent)
+        }
+
+        // Return the count
+        return count
+    }
+}

package/src/index.ts

@@ -1,4 +1,17 @@
-export * from './databaseConnection'
-export * from './serverConnection'
-export * from './datastoreAbstract'
-export * from './hydrateEntity'
+export * from './application/model-controller'
+export * from './application/read-only-model-controller'
+export * from './domain/events/domain-event'
+export * from './domain/events/event-types'
+export * from './domain/events/mutation-event'
+export * from './domain/events/query-event'
+export * from './domain/events/request-event'
+export * from './domain/interfaces/repository'
+export * from './domain/models/pagination'
+export * from './domain/services/base-model-service'
+export * from './domain/services/model-service'
+export * from './domain/services/model-service-args'
+export * from './domain/services/read-only-model-service'
+export * from './shared/utils/schema-inference'
+export * from './shared/utils/schema-inheritance'
+export * from './test/mock/models/mock-book-models'
+export * from './test/mock/repositories/mock-memory-repository'

package/src/shared/utils/schema-inference.ts

@@ -0,0 +1,26 @@
+import type { AnyModelSchema, InferModelInput, InferModelOutput } from '@declaro/core'
+import type { IPagination } from '../../domain/models/pagination'
+
+export interface ISearchResults<T> {
+    results: T[]
+    pagination: IPagination
+}
+
+export type InferLookup<TSchema extends AnyModelSchema> = InferModelInput<TSchema['definition']['lookup']>
+export type InferDetail<TSchema extends AnyModelSchema> = InferModelOutput<TSchema['definition']['detail']>
+export type InferFilters<TSchema extends AnyModelSchema> = InferModelInput<TSchema['definition']['filters']>
+export type InferSummary<TSchema extends AnyModelSchema> = InferModelOutput<TSchema['definition']['summary']>
+export type InferSort<TSchema extends AnyModelSchema> = InferModelInput<TSchema['definition']['sort']>
+export type InferInput<TSchema extends AnyModelSchema> = InferModelInput<TSchema['definition']['input']>
+export type InferSearchResults<TSchema extends AnyModelSchema> = ISearchResults<InferSummary<TSchema>>
+export type InferEntityMetadata<TSchema extends AnyModelSchema> = ReturnType<TSchema['getEntityMetadata']>
+export type InferPrimaryKeyType<TSchema extends AnyModelSchema> =
+    InferLookup<TSchema>[InferEntityMetadata<TSchema>['primaryKey']]
+
+export type InferSummarySchema<TSchema extends AnyModelSchema> = TSchema['definition']['summary']['schema']
+export type InferDetailSchema<TSchema extends AnyModelSchema> = TSchema['definition']['detail']['schema']
+export type InferLookupSchema<TSchema extends AnyModelSchema> = TSchema['definition']['lookup']['schema']
+export type InferInputSchema<TSchema extends AnyModelSchema> = TSchema['definition']['input']['schema']
+export type InferFiltersSchema<TSchema extends AnyModelSchema> = TSchema['definition']['filters']['schema']
+export type InferSortSchema<TSchema extends AnyModelSchema> = TSchema['definition']['sort']['schema']
+export type InferSearchResultsSchema<TSchema extends AnyModelSchema> = TSchema['definition']['search']['schema']

package/src/shared/utils/schema-inheritance.test.ts

@@ -0,0 +1,295 @@
+import { describe, expect, test } from 'bun:test'
+import type { ChildSchema } from './schema-inheritance'
+import type { IAnimalTraitSchema } from './test/animal-trait-schema'
+import type { IElephantSchema } from './test/elephant-schema'
+import type { IAnimalSchema } from './test/animal-schema'
+import type { IElephantTraitSchema } from './test/elephant-trait-schema'
+import type { InferDetail } from './schema-inference'
+
+// Service Classes using ChildSchema
+
+class AnimalService<TSchema extends ChildSchema<IAnimalSchema>> {
+    getTraits(animal?: InferDetail<TSchema>): InferDetail<IAnimalTraitSchema>[] {
+        return animal?.traits ?? []
+    }
+}
+
+class ElephantService extends AnimalService<IElephantSchema> {
+    getTrunkLength(elephant?: InferDetail<IElephantSchema>): number {
+        return elephant?.trunkLength ?? 0
+    }
+}
+
+class AnimalTraitService<TSchema extends ChildSchema<IAnimalTraitSchema>> {
+    isTitleLong(trait?: InferDetail<TSchema>): boolean {
+        return (trait?.title.length ?? 0) > 10
+    }
+}
+
+class ElephantTraitService extends AnimalTraitService<IElephantTraitSchema> {
+    isSharpTrait(trait?: InferDetail<IElephantTraitSchema>): boolean {
+        return trait?.isSharp ?? false
+    }
+}
+
+describe('Schema Inheritance Utils', () => {
+    describe('AnimalService', () => {
+        test('should get traits from animal detail', () => {
+            const service = new AnimalService()
+            const animal = {
+                name: 'Lion',
+                sound: 'Roar',
+                traits: [
+                    { title: 'Carnivore', description: 'Eats meat', animal: undefined },
+                    { title: 'Predator', description: 'Hunts prey', animal: undefined },
+                ],
+            }
+
+            const traits = service.getTraits(animal)
+
+            expect(traits).toHaveLength(2)
+            expect(traits[0].title).toBe('Carnivore')
+            expect(traits[1].title).toBe('Predator')
+        })
+
+        test('should return empty array when animal has no traits', () => {
+            const service = new AnimalService()
+            const animal = {
+                name: 'Lion',
+                sound: 'Roar',
+                traits: [],
+            }
+
+            const traits = service.getTraits(animal)
+
+            expect(traits).toEqual([])
+        })
+
+        test('should return empty array when animal is undefined', () => {
+            const service = new AnimalService()
+
+            const traits = service.getTraits(undefined)
+
+            expect(traits).toEqual([])
+        })
+    })
+
+    describe('ElephantService', () => {
+        test('should inherit getTraits from AnimalService', () => {
+            const service = new ElephantService()
+            const elephant = {
+                name: 'Dumbo',
+                sound: 'Trumpet',
+                trunkLength: 150,
+                traits: [
+                    {
+                        title: 'Long trunk',
+                        description: 'Very long trunk',
+                        isSharp: false,
+                        length: 150,
+                        animal: undefined,
+                    },
+                ],
+            }
+
+            const traits = service.getTraits(elephant)
+
+            expect(traits).toHaveLength(1)
+            expect(traits[0].title).toBe('Long trunk')
+        })
+
+        test('should get trunk length from elephant', () => {
+            const service = new ElephantService()
+            const elephant = {
+                name: 'Dumbo',
+                sound: 'Trumpet',
+                trunkLength: 150,
+                traits: [],
+            }
+
+            const trunkLength = service.getTrunkLength(elephant)
+
+            expect(trunkLength).toBe(150)
+        })
+
+        test('should return 0 when elephant is undefined', () => {
+            const service = new ElephantService()
+
+            const trunkLength = service.getTrunkLength(undefined)
+
+            expect(trunkLength).toBe(0)
+        })
+
+        test('should handle elephant with zero trunk length', () => {
+            const service = new ElephantService()
+            const elephant = {
+                name: 'Baby Elephant',
+                sound: 'Squeak',
+                trunkLength: 0,
+                traits: [],
+            }
+
+            const trunkLength = service.getTrunkLength(elephant)
+
+            expect(trunkLength).toBe(0)
+        })
+    })
+
+    describe('AnimalTraitService', () => {
+        test('should identify long titles', () => {
+            const service = new AnimalTraitService()
+            const trait = {
+                title: 'This is a very long title',
+                description: 'Description',
+                animal: undefined,
+            }
+
+            const isLong = service.isTitleLong(trait)
+
+            expect(isLong).toBe(true)
+        })
+
+        test('should identify short titles', () => {
+            const service = new AnimalTraitService()
+            const trait = {
+                title: 'Short',
+                description: 'Description',
+                animal: undefined,
+            }
+
+            const isLong = service.isTitleLong(trait)
+
+            expect(isLong).toBe(false)
+        })
+
+        test('should handle exactly 10 character titles as short', () => {
+            const service = new AnimalTraitService()
+            const trait = {
+                title: '1234567890',
+                description: 'Description',
+                animal: undefined,
+            }
+
+            const isLong = service.isTitleLong(trait)
+
+            expect(isLong).toBe(false)
+        })
+
+        test('should return false when trait is undefined', () => {
+            const service = new AnimalTraitService()
+
+            const isLong = service.isTitleLong(undefined)
+
+            expect(isLong).toBe(false)
+        })
+    })
+
+    describe('ElephantTraitService', () => {
+        test('should inherit isTitleLong from AnimalTraitService', () => {
+            const service = new ElephantTraitService()
+            const trait = {
+                title: 'Very long elephant trait title',
+                description: 'Description',
+                isSharp: true,
+                length: 50,
+                animal: undefined,
+            }
+
+            const isLong = service.isTitleLong(trait)
+
+            expect(isLong).toBe(true)
+        })
+
+        test('should identify sharp traits', () => {
+            const service = new ElephantTraitService()
+            const trait = {
+                title: 'Sharp tusk',
+                description: 'A sharp tusk',
+                isSharp: true,
+                length: 100,
+                animal: undefined,
+            }
+
+            const isSharp = service.isSharpTrait(trait)
+
+            expect(isSharp).toBe(true)
+        })
+
+        test('should identify non-sharp traits', () => {
+            const service = new ElephantTraitService()
+            const trait = {
+                title: 'Soft ear',
+                description: 'A soft ear',
+                isSharp: false,
+                length: 50,
+                animal: undefined,
+            }
+
+            const isSharp = service.isSharpTrait(trait)
+
+            expect(isSharp).toBe(false)
+        })
+
+        test('should return false when trait is undefined', () => {
+            const service = new ElephantTraitService()
+
+            const isSharp = service.isSharpTrait(undefined)
+
+            expect(isSharp).toBe(false)
+        })
+
+        test('should handle both inherited and own methods', () => {
+            const service = new ElephantTraitService()
+            const trait = {
+                title: 'Long and sharp tusk trait',
+                description: 'Description',
+                isSharp: true,
+                length: 150,
+                animal: undefined,
+            }
+
+            const isLong = service.isTitleLong(trait)
+            const isSharp = service.isSharpTrait(trait)
+
+            expect(isLong).toBe(true)
+            expect(isSharp).toBe(true)
+        })
+    })
+
+    describe('Schema Inheritance Type Safety', () => {
+        test('should allow ElephantService to work with elephant-specific properties', () => {
+            const service = new ElephantService()
+            const elephant = {
+                name: 'Babar',
+                sound: 'Trumpet',
+                trunkLength: 200,
+                traits: [],
+            }
+
+            // Should compile and work with both animal and elephant properties
+            const traits = service.getTraits(elephant)
+            const trunkLength = service.getTrunkLength(elephant)
+
+            expect(traits).toEqual([])
+            expect(trunkLength).toBe(200)
+        })
+
+        test('should allow ElephantTraitService to work with elephant trait properties', () => {
+            const service = new ElephantTraitService()
+            const trait = {
+                title: 'Trait',
+                description: 'Desc',
+                isSharp: true,
+                length: 75,
+                animal: undefined,
+            }
+
+            // Should compile and work with both animal trait and elephant trait properties
+            const isLong = service.isTitleLong(trait)
+            const isSharp = service.isSharpTrait(trait)
+
+            expect(isLong).toBe(false)
+            expect(isSharp).toBe(true)
+        })
+    })
+})

package/src/shared/utils/schema-inheritance.ts

@@ -0,0 +1,28 @@
+import type { AnyModelSchema, Model, ModelSchema } from '@declaro/core'
+import type { InferEntityMetadata } from './schema-inference'
+
+/**
+ * Represents a child schema that inherits from a parent schema.
+ * This is useful for creating schemas that extend the functionality of an existing schema.
+ * It replaces the schema name and all model names with a string type.
+ *
+ * @warning This type is intended for use in generic types. In most cases, you should use concrete schemas for inheritance for best type inference.
+ *
+ * @template TSchema - The parent schema type.
+ * @example
+ * ```ts
+ * import { ModelSchema, ChildSchema } from '@declaro/core';
+ *
+ * export class ParentService<TSchema extends ChildSchema<typeof ParentSchema>> extends ModelService<TSchema> {
+ *     constructor(args: IModelServiceArgs<TSchema>) {
+ *         super(args);
+ *     }
+ * }
+ */
+export type ChildSchema<TSchema extends AnyModelSchema> = ModelSchema<
+    string,
+    {
+        [K in keyof TSchema['definition']]: Model<string, TSchema['definition'][K]['schema']>
+    },
+    InferEntityMetadata<TSchema>
+>

package/src/shared/utils/test/animal-schema.ts

@@ -0,0 +1,46 @@
+// Animal Schema
+
+import { ModelSchema } from '@declaro/core'
+import { sortArray, ZodModel } from '@declaro/zod'
+import z4 from 'zod/v4'
+import { AnimalTraitsDetailSchema, AnimalTraitsSummarySchema } from './animal-trait-schema'
+
+export const AnimalDetailSchema = z4.object({
+    name: z4.string(),
+    sound: z4.string(),
+    get traits() {
+        return z4.array(AnimalTraitsDetailSchema)
+    },
+})
+
+export const AnimalLookupSchema = z4.object({
+    id: z4.number(),
+})
+
+export const AnimalFiltersSchema = z4.object({
+    text: z4.string().optional(),
+    sound: z4.string().optional(),
+})
+
+export const AnimalSortSchema = sortArray(['name', 'sound'])
+
+export const AnimalSummarySchema = z4.object({
+    name: z4.string(),
+    sound: z4.string(),
+    get traits() {
+        return z4.array(AnimalTraitsSummarySchema)
+    },
+})
+
+export const AnimalSchema = ModelSchema.create('AnimalSchema')
+    .read({
+        detail: (h) => new ZodModel('AnimalDetail', AnimalDetailSchema),
+        lookup: (h) => new ZodModel('AnimalLookup', AnimalLookupSchema),
+    })
+    .search({
+        filters: (h) => new ZodModel('AnimalFilters', AnimalFiltersSchema),
+        sort: (h) => new ZodModel('AnimalSort', AnimalSortSchema),
+        summary: (h) => new ZodModel('AnimalSummary', AnimalSummarySchema),
+    })
+
+export type IAnimalSchema = typeof AnimalSchema

package/src/shared/utils/test/animal-trait-schema.ts

@@ -0,0 +1,45 @@
+import { sortArray, ZodModel } from '@declaro/zod'
+import { AnimalDetailSchema, AnimalSummarySchema } from './animal-schema'
+
+// Animal Traits Schema
+
+import { ModelSchema } from '@declaro/core'
+import z4 from 'zod/v4'
+
+export const AnimalTraitsDetailSchema = z4.object({
+    title: z4.string(),
+    description: z4.string(),
+    get animal() {
+        return AnimalDetailSchema.optional()
+    },
+})
+
+export const AnimalTraitsSummarySchema = z4.object({
+    title: z4.string(),
+    get animal() {
+        return AnimalSummarySchema.optional()
+    },
+})
+
+export const AnimalTraitsLookupSchema = z4.object({
+    id: z4.number(),
+})
+
+export const AnimalTraitsFiltersSchema = z4.object({
+    text: z4.string().optional(),
+})
+
+export const AnimalTraitsSortSchema = sortArray(['title'])
+
+export const AnimalTraitsSchema = ModelSchema.create('AnimalTraitsSchema')
+    .read({
+        detail: (h) => new ZodModel('AnimalTraitsDetail', AnimalTraitsDetailSchema),
+        lookup: (h) => new ZodModel('AnimalTraitsLookup', AnimalTraitsLookupSchema),
+    })
+    .search({
+        filters: (h) => new ZodModel('AnimalTraitsFilters', AnimalTraitsFiltersSchema),
+        sort: (h) => new ZodModel('AnimalTraitsSort', AnimalTraitsSortSchema),
+        summary: (h) => new ZodModel('AnimalTraitsSummary', AnimalTraitsSummarySchema),
+    })
+
+export type IAnimalTraitSchema = typeof AnimalTraitsSchema