@declaro/data 2.0.0-beta.97 → 2.0.0-beta.98

package/dist/ts/domain/services/model-service.d.ts

@@ -9,6 +9,14 @@ export interface IUpdateOptions extends IActionOptions {
 }
 export declare class ModelService<TSchema extends AnyModelSchema> extends ReadOnlyModelService<TSchema> {
     constructor(args: IModelServiceArgs<TSchema>);
+    /**
+     * Normalizes input data before processing. This method can be overridden by subclasses
+     * to implement custom input normalization logic (e.g., trimming strings, setting defaults, etc.).
+     * By default, this method returns the input unchanged.
+     * @param input The input data to normalize.
+     * @returns The normalized input data.
+     */
+    protected normalizeInput(input: InferInput<TSchema>): Promise<InferInput<TSchema>>;
     /**
      * Removes a record by its lookup criteria.
      * @param lookup The lookup criteria to find the record.

package/dist/ts/domain/services/model-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-service.d.ts","sourceRoot":"","sources":["../../../../src/domain/services/model-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AAG7G,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D,MAAM,WAAW,cAAe,SAAQ,cAAc;CAAG;AACzD,MAAM,WAAW,cAAe,SAAQ,cAAc;CAAG;AAEzD,qBAAa,YAAY,CAAC,OAAO,SAAS,cAAc,CAAE,SAAQ,oBAAoB,CAAC,OAAO,CAAC;gBAC/E,IAAI,EAAE,iBAAiB,CAAC,OAAO,CAAC;IAI5C;;;;OAIG;IACG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAsBlG;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAsB7F,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAsB3F,MAAM,CACR,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAC5B,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAC1B,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAsBhC;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IA+ClH;;;;;OAKG;IACG,UAAU,CACZ,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,EAC7B,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,GAC1C,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;CA4IrC"}
+{"version":3,"file":"model-service.d.ts","sourceRoot":"","sources":["../../../../src/domain/services/model-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AAG7G,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC7D,OAAO,EAAE,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAA;AACnF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D,MAAM,WAAW,cAAe,SAAQ,cAAc;CAAG;AACzD,MAAM,WAAW,cAAe,SAAQ,cAAc;CAAG;AAEzD,qBAAa,YAAY,CAAC,OAAO,SAAS,cAAc,CAAE,SAAQ,oBAAoB,CAAC,OAAO,CAAC;gBAC/E,IAAI,EAAE,iBAAiB,CAAC,OAAO,CAAC;IAI5C;;;;;;OAMG;cACa,cAAc,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAIxF;;;;OAIG;IACG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAsBlG;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;IAsB7F,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAyB3F,MAAM,CACR,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,EAC5B,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAC1B,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAyBhC;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAkDlH;;;;;OAKG;IACG,UAAU,CACZ,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,EAC7B,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,GAC1C,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;CA+IrC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@declaro/data",
-    "version": "2.0.0-beta.97",
+    "version": "2.0.0-beta.98",
     "description": "A data-mapper framework for managing application data across integrated systems.",
     "main": "dist/node/index.cjs",
     "module": "dist/node/index.js",
@@ -22,9 +22,9 @@
         "@declaro/zod": "^2.0.0-beta.51"
     },
     "devDependencies": {
-        "@declaro/auth": "^2.0.0-beta.97",
-        "@declaro/core": "^2.0.0-beta.97",
-        "@declaro/zod": "^2.0.0-beta.97",
+        "@declaro/auth": "^2.0.0-beta.98",
+        "@declaro/core": "^2.0.0-beta.98",
+        "@declaro/zod": "^2.0.0-beta.98",
         "crypto-browserify": "^3.12.1",
         "typescript": "^5.8.3",
         "uuid": "^11.1.0",
@@ -43,5 +43,5 @@
         "require": "./dist/node/index.cjs",
         "browser": "./dist/browser/index.js"
     },
-    "gitHead": "f5735a57bfd6cc342c60e9974395c389f43c3f93"
+    "gitHead": "5f998cfb45e04482853d7511c04348d668c292da"
 }

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

@@ -628,4 +628,249 @@ describe('ModelService', () => {
             expect(results).toEqual(inputs)
         })
     })
+
+    describe('normalizeInput functionality', () => {
+        class TestModelService extends ModelService<typeof mockSchema> {
+            public testNormalizeInput(input: any) {
+                return this.normalizeInput(input)
+            }
+
+            protected async normalizeInput(input: any) {
+                return {
+                    ...input,
+                    title: input.title?.trim(),
+                    author: input.author?.trim(),
+                    normalizedAt: new Date('2023-01-01'),
+                }
+            }
+        }
+
+        let testService: TestModelService
+
+        beforeEach(() => {
+            testService = new TestModelService({ repository, emitter, schema: mockSchema, namespace })
+        })
+
+        it('should use default normalizeInput method (no changes) when not overridden', async () => {
+            const input = { title: '  Test Book  ', author: '  Author Name  ', publishedDate: new Date() }
+            const normalized = await service['normalizeInput'](input)
+
+            expect(normalized).toEqual(input)
+            expect(normalized).toBe(input) // Should be the exact same reference
+        })
+
+        it('should use custom normalizeInput method for create operation', async () => {
+            const input = { title: '  Test Book  ', author: '  Author Name  ', publishedDate: new Date() }
+            const createdItem = await testService.create(input)
+
+            expect(createdItem.title).toBe('Test Book')
+            expect(createdItem.author).toBe('Author Name')
+            expect((createdItem as any).normalizedAt).toEqual(new Date('2023-01-01'))
+        })
+
+        it('should use custom normalizeInput method for update operation', async () => {
+            const input = { id: 42, title: 'Original Book', author: 'Original Author', publishedDate: new Date() }
+            const createdItem = await testService.create(input)
+
+            const updateInput = { title: '  Updated Book  ', author: '  Updated Author  ', publishedDate: new Date() }
+            const updatedItem = await testService.update({ id: createdItem.id }, updateInput)
+
+            expect(updatedItem.title).toBe('Updated Book')
+            expect(updatedItem.author).toBe('Updated Author')
+            expect((updatedItem as any).normalizedAt).toEqual(new Date('2023-01-01'))
+        })
+
+        it('should use custom normalizeInput method for upsert operation', async () => {
+            const input = { id: 42, title: '  Test Book  ', author: '  Author Name  ', publishedDate: new Date() }
+            const upsertedItem = await testService.upsert(input)
+
+            expect(upsertedItem.title).toBe('Test Book')
+            expect(upsertedItem.author).toBe('Author Name')
+            expect((upsertedItem as any).normalizedAt).toEqual(new Date('2023-01-01'))
+
+            // Upsert again with different data
+            const updateInput = {
+                id: 42,
+                title: '  Updated Book  ',
+                author: '  Updated Author  ',
+                publishedDate: new Date(),
+            }
+            const updatedItem = await testService.upsert(updateInput)
+
+            expect(updatedItem.title).toBe('Updated Book')
+            expect(updatedItem.author).toBe('Updated Author')
+            expect((updatedItem as any).normalizedAt).toEqual(new Date('2023-01-01'))
+        })
+
+        it('should use custom normalizeInput method for bulkUpsert operation', async () => {
+            const inputs = [
+                { id: 1, title: '  Book One  ', author: '  Author One  ', publishedDate: new Date() },
+                { id: 2, title: '  Book Two  ', author: '  Author Two  ', publishedDate: new Date() },
+                { title: '  Book Three  ', author: '  Author Three  ', publishedDate: new Date() }, // No ID - will be created
+            ]
+
+            const results = await testService.bulkUpsert(inputs)
+
+            expect(results).toHaveLength(3)
+            expect(results[0].title).toBe('Book One')
+            expect(results[0].author).toBe('Author One')
+            expect((results[0] as any).normalizedAt).toEqual(new Date('2023-01-01'))
+
+            expect(results[1].title).toBe('Book Two')
+            expect(results[1].author).toBe('Author Two')
+            expect((results[1] as any).normalizedAt).toEqual(new Date('2023-01-01'))
+
+            expect(results[2].title).toBe('Book Three')
+            expect(results[2].author).toBe('Author Three')
+            expect((results[2] as any).normalizedAt).toEqual(new Date('2023-01-01'))
+        })
+
+        it('should preserve events order with normalized input in create operation', async () => {
+            const input = { title: '  Test Book  ', author: '  Author Name  ', publishedDate: new Date() }
+            await testService.create(input)
+
+            // Debug: Let's see what was actually called
+            const beforeCreateCall = beforeCreateSpy.mock.calls[0][0]
+            const afterCreateCall = afterCreateSpy.mock.calls[0][0]
+
+            expect(beforeCreateCall.meta.input.title).toBe('Test Book')
+            expect(beforeCreateCall.meta.input.author).toBe('Author Name')
+            expect(beforeCreateCall.meta.input.normalizedAt).toEqual(new Date('2023-01-01'))
+
+            expect(afterCreateCall.meta.input.title).toBe('Test Book')
+            expect(afterCreateCall.meta.input.author).toBe('Author Name')
+            expect(afterCreateCall.meta.input.normalizedAt).toEqual(new Date('2023-01-01'))
+        })
+
+        it('should handle complex async normalization logic', async () => {
+            class ComplexNormalizationService extends ModelService<typeof mockSchema> {
+                protected async normalizeInput(input: any) {
+                    // Simulate async operations like database lookups, API calls, etc.
+                    await new Promise((resolve) => setTimeout(resolve, 10))
+
+                    const normalized = { ...input }
+
+                    // Complex normalization logic
+                    if (normalized.title) {
+                        normalized.title = normalized.title
+                            .trim()
+                            .replace(/\s+/g, ' ')
+                            .toLowerCase()
+                            .replace(/\b\w/g, (l: string) => l.toUpperCase()) // Title case
+                    }
+
+                    if (normalized.author) {
+                        normalized.author = normalized.author.trim()
+                    }
+
+                    // Add metadata
+                    normalized.processedAt = new Date('2023-01-01')
+                    normalized.version = (normalized.version || 0) + 1
+
+                    return normalized
+                }
+            }
+
+            const complexService = new ComplexNormalizationService({
+                repository,
+                emitter,
+                schema: mockSchema,
+                namespace,
+            })
+
+            const input = {
+                title: '  the  great   book  ',
+                author: '  John Doe  ',
+                publishedDate: new Date(),
+            }
+
+            const result = await complexService.create(input)
+
+            expect(result.title).toBe('The Great Book')
+            expect(result.author).toBe('John Doe')
+            expect((result as any).processedAt).toEqual(new Date('2023-01-01'))
+            expect((result as any).version).toBe(1)
+        })
+
+        it('should call normalizeInput method exactly once per input during bulkUpsert with Promise.all', async () => {
+            const normalizeInputSpy = mock(async (input: any) => ({ ...input, normalized: true }))
+
+            class SpyService extends ModelService<typeof mockSchema> {
+                protected async normalizeInput(input: any) {
+                    return normalizeInputSpy(input)
+                }
+            }
+
+            const spyService = new SpyService({ repository, emitter, schema: mockSchema, namespace })
+
+            const inputs = [
+                { id: 1, title: 'Book One', author: 'Author One', publishedDate: new Date() },
+                { id: 2, title: 'Book Two', author: 'Author Two', publishedDate: new Date() },
+            ]
+
+            await spyService.bulkUpsert(inputs)
+
+            expect(normalizeInputSpy).toHaveBeenCalledTimes(2)
+            expect(normalizeInputSpy).toHaveBeenNthCalledWith(1, inputs[0])
+            expect(normalizeInputSpy).toHaveBeenNthCalledWith(2, inputs[1])
+        })
+
+        it('should handle async normalization errors gracefully', async () => {
+            class ErrorNormalizationService extends ModelService<typeof mockSchema> {
+                protected async normalizeInput(input: any) {
+                    if (input.title === 'ERROR') {
+                        throw new Error('Normalization failed')
+                    }
+                    return input
+                }
+            }
+
+            const errorService = new ErrorNormalizationService({
+                repository,
+                emitter,
+                schema: mockSchema,
+                namespace,
+            })
+
+            const input = { title: 'ERROR', author: 'Author Name', publishedDate: new Date() }
+
+            await expect(errorService.create(input)).rejects.toThrow('Normalization failed')
+        })
+
+        it('should process bulk normalization in parallel for performance', async () => {
+            const processingTimes: number[] = []
+
+            class TimingNormalizationService extends ModelService<typeof mockSchema> {
+                protected async normalizeInput(input: any) {
+                    const start = Date.now()
+                    // Simulate some async work
+                    await new Promise((resolve) => setTimeout(resolve, 50))
+                    processingTimes.push(Date.now() - start)
+                    return input
+                }
+            }
+
+            const timingService = new TimingNormalizationService({
+                repository,
+                emitter,
+                schema: mockSchema,
+                namespace,
+            })
+
+            const inputs = [
+                { id: 1, title: 'Book One', author: 'Author One', publishedDate: new Date() },
+                { id: 2, title: 'Book Two', author: 'Author Two', publishedDate: new Date() },
+                { id: 3, title: 'Book Three', author: 'Author Three', publishedDate: new Date() },
+            ]
+
+            const start = Date.now()
+            await timingService.bulkUpsert(inputs)
+            const totalTime = Date.now() - start
+
+            // With Promise.all, total time should be closer to single operation time rather than sum of all
+            // Allow some variance for test stability
+            expect(totalTime).toBeLessThan(150) // Much less than 3 * 50ms = 150ms
+            expect(processingTimes).toHaveLength(3)
+        })
+    })
 })

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

@@ -14,6 +14,17 @@ export class ModelService<TSchema extends AnyModelSchema> extends ReadOnlyModelS
         super(args)
     }
 
+    /**
+     * Normalizes input data before processing. This method can be overridden by subclasses
+     * to implement custom input normalization logic (e.g., trimming strings, setting defaults, etc.).
+     * By default, this method returns the input unchanged.
+     * @param input The input data to normalize.
+     * @returns The normalized input data.
+     */
+    protected async normalizeInput(input: InferInput<TSchema>): Promise<InferInput<TSchema>> {
+        return input
+    }
+
     /**
      * Removes a record by its lookup criteria.
      * @param lookup The lookup criteria to find the record.
@@ -70,20 +81,23 @@ export class ModelService<TSchema extends AnyModelSchema> extends ReadOnlyModelS
     }
 
     async create(input: InferInput<TSchema>, options?: ICreateOptions): Promise<InferDetail<TSchema>> {
+        // Normalize the input data
+        const normalizedInput = await this.normalizeInput(input)
+
         // Emit the before create event
         const beforeCreateEvent = new MutationEvent<InferDetail<TSchema>, InferInput<TSchema>>(
             this.getDescriptor(ModelMutationAction.BeforeCreate),
-            input,
+            normalizedInput,
         )
         await this.emitter.emitAsync(beforeCreateEvent)
 
         // Perform the creation
-        const result = await this.repository.create(input, options)
+        const result = await this.repository.create(normalizedInput, options)
 
         // Emit the after create event
         const afterCreateEvent = new MutationEvent<InferDetail<TSchema>, InferInput<TSchema>>(
             this.getDescriptor(ModelMutationAction.AfterCreate),
-            input,
+            normalizedInput,
         ).setResult(result)
         await this.emitter.emitAsync(afterCreateEvent)
 
@@ -96,20 +110,23 @@ export class ModelService<TSchema extends AnyModelSchema> extends ReadOnlyModelS
         input: InferInput<TSchema>,
         options?: IUpdateOptions,
     ): Promise<InferDetail<TSchema>> {
+        // Normalize the input data
+        const normalizedInput = await this.normalizeInput(input)
+
         // Emit the before update event
         const beforeUpdateEvent = new MutationEvent<InferDetail<TSchema>, InferInput<TSchema>>(
             this.getDescriptor(ModelMutationAction.BeforeUpdate),
-            input,
+            normalizedInput,
         )
         await this.emitter.emitAsync(beforeUpdateEvent)
 
         // Perform the update
-        const result = await this.repository.update(lookup, input, options)
+        const result = await this.repository.update(lookup, normalizedInput, options)
 
         // Emit the after update event
         const afterUpdateEvent = new MutationEvent<InferDetail<TSchema>, InferInput<TSchema>>(
             this.getDescriptor(ModelMutationAction.AfterUpdate),
-            input,
+            normalizedInput,
         ).setResult(result)
         await this.emitter.emitAsync(afterUpdateEvent)
 
@@ -124,7 +141,10 @@ export class ModelService<TSchema extends AnyModelSchema> extends ReadOnlyModelS
      * @returns The upserted record.
      */
     async upsert(input: InferInput<TSchema>, options?: ICreateOptions | IUpdateOptions): Promise<InferDetail<TSchema>> {
-        const primaryKeyValue = this.getPrimaryKeyValue(input)
+        // Normalize the input data
+        const normalizedInput = await this.normalizeInput(input)
+
+        const primaryKeyValue = this.getPrimaryKeyValue(normalizedInput)
 
         let beforeOperation: ModelMutationAction
         let afterOperation: ModelMutationAction
@@ -152,17 +172,17 @@ export class ModelService<TSchema extends AnyModelSchema> extends ReadOnlyModelS
         // Emit the before upsert event
         const beforeUpsertEvent = new MutationEvent<InferDetail<TSchema>, InferInput<TSchema>>(
             this.getDescriptor(beforeOperation),
-            input,
+            normalizedInput,
         )
         await this.emitter.emitAsync(beforeUpsertEvent)
 
         // Perform the upsert operation
-        const result = await this.repository.upsert(input, options)
+        const result = await this.repository.upsert(normalizedInput, options)
 
         // Emit the after upsert event
         const afterUpsertEvent = new MutationEvent<InferDetail<TSchema>, InferInput<TSchema>>(
             this.getDescriptor(afterOperation),
-            input,
+            normalizedInput,
         ).setResult(result)
         await this.emitter.emitAsync(afterUpsertEvent)
 
@@ -184,6 +204,9 @@ export class ModelService<TSchema extends AnyModelSchema> extends ReadOnlyModelS
             return []
         }
 
+        // Normalize all input data in parallel using Promise.all
+        const normalizedInputs = await Promise.all(inputs.map((input) => this.normalizeInput(input)))
+
         // Build a map of primary key to input and lookup info
         type EntityInfo = {
             input: InferInput<TSchema>
@@ -196,8 +219,8 @@ export class ModelService<TSchema extends AnyModelSchema> extends ReadOnlyModelS
         const entityInfoMap = new Map<string | number, EntityInfo>()
         const inputsWithoutPrimaryKey: InferInput<TSchema>[] = []
 
-        // Process each input and organize by primary key
-        for (const input of inputs) {
+        // Process each normalized input and organize by primary key
+        for (const input of normalizedInputs) {
             const primaryKeyValue = this.getPrimaryKeyValue(input)
 
             if (primaryKeyValue !== undefined) {
@@ -264,8 +287,8 @@ export class ModelService<TSchema extends AnyModelSchema> extends ReadOnlyModelS
         // Emit all before events
         await Promise.all(beforeEvents.map((event) => this.emitter.emitAsync(event)))
 
-        // Perform the bulk upsert operation
-        const results = await this.repository.bulkUpsert(inputs, options)
+        // Perform the bulk upsert operation with normalized inputs
+        const results = await this.repository.bulkUpsert(normalizedInputs, options)
 
         // Create a map of result primary keys to results for matching
         const resultsByPrimaryKey = new Map<string | number, InferDetail<TSchema>>()