chore: improvement of resource

Author: tnramalho

examples/sample-server/src/app.module.ts

@@ -11,25 +11,25 @@ import {
   USER_ENTITY_KEY,
 } from './auth';
 import {
-  createPetResource,
+  petResource,
   PetEntity,
   PetTagEntity,
   PET_TAG_ENTITY_KEY,
 } from './resources/pet';
 import {
-  createPetVaccinationResource,
+  petVaccinationResource,
   PetVaccinationEntity,
 } from './resources/pet-vaccination';
-import { createTagResource, TagEntity } from './resources/tag';
+import { tagResource, TagEntity } from './resources/tag';
 import { PetShareEntity, PetShareModule } from './resources/pet-share';
 import { PET_SHARE_ENTITY_KEY } from './resources/pet-share/pet-share.constants';
 import { PetTransferModule } from './resources/pet-transfer';
 import { AdminModule } from './admin';
 import {
   AppointmentEntity,
   ReminderEntity,
-  createAppointmentResource,
-  createReminderResource,
+  appointmentResource,
+  reminderResource,
 } from './resources/appointment';
 import { AuditLogEntity, AuditModule } from './audit';
 import { AUDIT_LOG_ENTITY_KEY } from './audit/audit-log.constants';
@@ -79,11 +79,11 @@ import { EventsModule } from './events';
       // pet and petVaccination entities are auto-contributed by their
       // respective defineResource() bundles below.
       resources: [
-        createPetResource(),
-        createPetVaccinationResource(),
-        createTagResource(),
-        createAppointmentResource(),
-        createReminderResource(),
+        petResource,
+        petVaccinationResource,
+        tagResource,
+        appointmentResource,
+        reminderResource,
       ],
     }),
     PetShareModule,

examples/sample-server/src/resources/appointment/appointment.resource.ts

@@ -2,15 +2,13 @@ import { Operation } from '@concepta/nestjs-common';
 import { defineResource } from '@bitwild/rockets';
 import { OwnerScopeHook } from '@bitwild/rockets-core';
 import { AppointmentEntity } from './appointment.entity';
+import { ReminderEntity } from './reminder.entity';
 import {
   AppointmentCreateDto,
   AppointmentResponseDto,
 } from './appointment.dto';
 import { AppointmentCreateHandler } from './appointment-create.handler';
-import {
-  APPOINTMENT_ENTITY_KEY,
-  REMINDER_ENTITY_KEY,
-} from './appointment.constants';
+import { APPOINTMENT_ENTITY_KEY } from './appointment.constants';
 
 /**
  * Create is handled by `AppointmentCreateHandler`, which wraps an
@@ -34,11 +32,7 @@ export const appointmentResource = defineResource({
     Operation.Create,
     Operation.Delete,
   ],
-  relations: [{ target: REMINDER_ENTITY_KEY, propertyName: 'reminders' }],
+  relations: (relation) => [relation(ReminderEntity, 'reminders')],
   hooks: [OwnerScopeHook],
   handlers: { create: AppointmentCreateHandler },
 });
-
-export function createAppointmentResource(): typeof appointmentResource {
-  return appointmentResource;
-}

examples/sample-server/src/resources/appointment/reminder.resource.ts

@@ -1,13 +1,19 @@
 import { Operation } from '@concepta/nestjs-common';
 import { defineResource } from '@bitwild/rockets';
 import { ReminderEntity } from './reminder.entity';
+import { AppointmentEntity } from './appointment.entity';
 import { ReminderResponseDto } from './appointment.dto';
 import { ReminderOwnerScopeHook } from './reminder-owner-scope.hook';
 import { REMINDER_ENTITY_KEY } from './appointment.constants';
 
 /**
  * Read-only — reminder lifecycle is owned by `AppointmentCreateHandler`
  * and future workflows (mark-sent, reschedule), not direct CRUD.
+ *
+ * The `relation()` helper declares the inverse of
+ * `AppointmentEntity.reminders`. The lazy `() => AppointmentEntity`
+ * thunk avoids a load-order cycle between `appointment.entity.ts` and
+ * `reminder.entity.ts`.
  */
 export const reminderResource = defineResource({
   key: REMINDER_ENTITY_KEY,
@@ -16,9 +22,6 @@ export const reminderResource = defineResource({
   tags: ['Reminders'],
   dto: { response: ReminderResponseDto },
   operations: [Operation.List, Operation.Read],
+  relations: (relation) => [relation(() => AppointmentEntity, 'appointment')],
   hooks: [ReminderOwnerScopeHook],
 });
-
-export function createReminderResource(): typeof reminderResource {
-  return reminderResource;
-}

examples/sample-server/src/resources/pet-vaccination/index.ts

@@ -1,2 +1,3 @@
-export { createPetVaccinationResource } from './pet-vaccination.resource';
+export { petVaccinationResource } from './pet-vaccination.resource';
 export { PetVaccinationEntity } from './pet-vaccination.entity';
+export { PET_VACCINATION_ENTITY_KEY } from './pet-vaccination.constants';

examples/sample-server/src/resources/pet-vaccination/pet-vaccination.resource.ts

@@ -1,6 +1,7 @@
 import { Operation } from '@concepta/nestjs-common';
 import { defineResource } from '@bitwild/rockets';
 import { PetVaccinationEntity } from './pet-vaccination.entity';
+import { PetEntity } from '../pet/pet.entity';
 import {
   PetVaccinationCreateDto,
   PetVaccinationResponseDto,
@@ -13,6 +14,11 @@ import { PET_VACCINATION_ENTITY_KEY } from './pet-vaccination.constants';
  * Exposes List/Read/Create/Delete (no Update). Paginated DTO is
  * auto-generated from `PetVaccinationResponseDto` — no hand-written
  * paginated class is required.
+ *
+ * The `relation()` helper declares the inverse of
+ * `PetEntity.vaccinations`. The lazy `() => PetEntity` thunk avoids a
+ * load-order cycle between `pet.entity.ts` and
+ * `pet-vaccination.entity.ts`.
  */
 export const petVaccinationResource = defineResource({
   key: PET_VACCINATION_ENTITY_KEY,
@@ -29,8 +35,5 @@ export const petVaccinationResource = defineResource({
     Operation.Create,
     Operation.Delete,
   ],
+  relations: (relation) => [relation(() => PetEntity, 'pet')],
 });
-
-export function createPetVaccinationResource(): typeof petVaccinationResource {
-  return petVaccinationResource;
-}

examples/sample-server/src/resources/pet/index.ts

@@ -1,4 +1,4 @@
-export { createPetResource } from './pet.resource';
+export { petResource } from './pet.resource';
 export { PetEntity } from './pet.entity';
 export { PetTagEntity } from './pet-tag.entity';
 export { PET_ENTITY_KEY } from './pet.constants';

examples/sample-server/src/resources/pet/pet.resource.ts

@@ -7,8 +7,8 @@ import { PetCreateHandler } from './pet-create.handler';
 import { PetUpdateHandler } from './pet-update.handler';
 import { PetOwnerOrSharedHook } from '../pet-share/pet-owner-or-shared.hook';
 import { AuditLogHook } from '../../audit/audit-log.hook';
-import { PET_VACCINATION_ENTITY_KEY } from '../pet-vaccination/pet-vaccination.constants';
-import { TAG_ENTITY_KEY } from '../tag/tag.constants';
+import { PetVaccinationEntity } from '../pet-vaccination/pet-vaccination.entity';
+import { TagEntity } from '../tag/tag.entity';
 import { PetTagSyncer } from './pet-tag.syncer';
 
 /**
@@ -36,9 +36,9 @@ export const petResource = defineResource({
     Operation.SoftDelete,
     Operation.Restore,
   ],
-  relations: [
-    { target: PET_VACCINATION_ENTITY_KEY, propertyName: 'vaccinations' },
-    { target: TAG_ENTITY_KEY, propertyName: 'tags' },
+  relations: (relation) => [
+    relation(PetVaccinationEntity, 'vaccinations'),
+    relation(TagEntity, 'tags'),
   ],
   hooks: [PetOwnerOrSharedHook, AuditLogHook],
   handlers: { create: PetCreateHandler, update: PetUpdateHandler },
@@ -50,7 +50,3 @@ export const petResource = defineResource({
     },
   },
 });
-
-export function createPetResource(): typeof petResource {
-  return petResource;
-}

examples/sample-server/src/resources/tag/tag.resource.ts

@@ -1,11 +1,18 @@
 import { defineResource } from '@bitwild/rockets';
 import { TagEntity } from './tag.entity';
+import { PetEntity } from '../pet/pet.entity';
 import { TagCreateDto, TagResponseDto, TagUpdateDto } from './tag.dto';
 import { TAG_ENTITY_KEY } from './tag.constants';
 
 /**
  * Shared global catalog — no owner scoping. Authorization for tag use
  * happens on the Pet side.
+ *
+ * The `relation()` helper declares the inverse of `PetEntity.tags`
+ * (M:N). The lazy `() => PetEntity` thunk avoids a load-order cycle
+ * between `pet.entity.ts` and `tag.entity.ts`. `include: 'never'` keeps
+ * the `pets` collection registered for cross-resource validation but
+ * off the controller surface — clients query pets-by-tag via `/pets`.
  */
 export const tagResource = defineResource({
   key: TAG_ENTITY_KEY,
@@ -17,8 +24,7 @@ export const tagResource = defineResource({
     create: TagCreateDto,
     update: TagUpdateDto,
   },
+  relations: (relation) => [
+    relation(() => PetEntity, 'pets', { include: 'never' }),
+  ],
 });
-
-export function createTagResource(): typeof tagResource {
-  return tagResource;
-}

packages/rockets-common/src/index.ts

@@ -158,3 +158,4 @@ export {
 } from './utils/error-logging.helper';
 export type { ErrorDetails } from './utils/error-logging.helper';
 export { createRepositoryContext } from './utils/repository-context.helper';
+export { stripUndefined } from './utils/strip-undefined.helper';

packages/rockets-common/src/utils/strip-undefined.helper.ts

@@ -0,0 +1,9 @@
+/**
+ * Drop keys whose value is `undefined`. Used so a PATCH that only sets
+ * some fields does not wipe the others back to `undefined` on update.
+ */
+export function stripUndefined<T extends object>(input: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(input).filter(([, v]) => v !== undefined),
+  ) as Partial<T>;
+}