@wisemen/one-of 0.0.15 → 0.0.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wisemen/one-of",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "publishConfig": {
     "access": "public"
   },
@@ -8,21 +8,24 @@
   "types": "./dist/index.d.ts",
   "type": "module",
   "files": [
-    "dist/"
+    "dist/",
+    "skills/"
   ],
   "peerDependencies": {
-    "@nestjs/common": ">=11.1.17",
-    "@nestjs/swagger": ">=11.2.6",
-    "class-transformer": ">=0.5.1",
-    "class-validator": ">=0.15.1",
-    "reflect-metadata": ">=0.2.2",
-    "typeorm": ">=1.0.0"
+    "@nestjs/common": "^11.1.19",
+    "@nestjs/swagger": "^11.4.2",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "reflect-metadata": "^0.2.2",
+    "typeorm": "^1.0.0"
   },
   "devDependencies": {
     "@types/node": "25.3.0",
     "eslint": "10.2.1",
+    "oxlint": "1.59.0",
     "expect": "30.2.0",
-    "typescript": ">=4.8.4 <=5.9.3",
+    "typescript": "^5.9.3",
+    "oxlint-tsgolint": "0.20.0",
     "@wisemen/eslint-config-nestjs": "1.1.1"
   },
   "author": "Kobe Kwanten",

package/skills/getting-started/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: getting-started
+description: Use when documenting discriminated NestJS API responses with Swagger.
+---
+
+# @wisemen/one-of - Getting Started
+
+Use `@wisemen/one-of` when an API response has a shared shape with a `type`
+discriminator and variant-specific `meta`.
+
+## Define The Response Shape
+
+```ts
+import { ApiProperty } from '@nestjs/swagger'
+import { OneOfMeta, OneOfMetaApiProperty, OneOfResponse, OneOfTypeApiProperty } from '@wisemen/one-of'
+
+enum NotificationType {
+  DRIVER_CREATED = 'driver.created',
+  DRIVER_UPDATED = 'driver.updated',
+}
+
+class Notification {} // example class that anchors the type and meta
+
+@OneOfResponse(Notification)
+class NotificationResponse {
+  @ApiProperty({ type: String, format: 'uuid' })
+  uuid: string
+
+  @OneOfTypeApiProperty()
+  type: NotificationType
+
+  @OneOfMetaApiProperty()
+  meta: unknown
+}
+
+@OneOfMeta(Notification, NotificationType.DRIVER_CREATED)
+class DriverCreatedNotificationMeta {
+  @ApiProperty({ type: String, format: 'uuid' })
+  driverUuid: string
+
+  @ApiProperty({type: String, format: 'date-time'})
+  createdAt: Date
+}
+
+@OneOfMeta(Notification, NotificationType.DRIVER_UPDATED)
+class DriverUpdatedNotificationMeta {
+  @ApiProperty({ type: String, format: 'uuid' })
+  driverUuid: string
+
+  @ApiProperty({type: String, format: 'date-time'})
+  updatedAt: Date
+}
+```
+
+Always pair `@OneOfResponse(...)` with both `@OneOfTypeApiProperty()` and
+`@OneOfMetaApiProperty()`. Each `@OneOfMeta(...)` registers one allowed
+discriminator value.
+
+## Expose It In Swagger
+
+Use `@OneOfApiResponse(...)` for direct controller responses:
+
+```ts
+import { Controller, Get } from '@nestjs/common'
+import { OneOfApiResponse } from '@wisemen/one-of'
+
+@Controller('/notifications')
+class NotificationController {
+  @Get()
+  @OneOfApiResponse(Notification)
+  async getNotification(): Promise<NotificationResponse> {
+    throw new Error('not implemented')
+  }
+}
+```
+
+Use `@OneOfApiExtraModels(...)` and `@OneOfApiProperty(...)` when the one-of
+response is nested inside another DTO:
+
+```ts
+import { OneOfApiExtraModels, OneOfApiProperty } from '@wisemen/one-of'
+
+@OneOfApiExtraModels(Notification)
+class GetNotificationsResponse {
+  @OneOfApiProperty(Notification, { isArray: true })
+  items: NotificationResponse[]
+}
+```