@workos/oagen-emitters 0.0.1 → 0.2.0

package/test/node/enums.test.ts

@@ -15,7 +15,6 @@ const ctx: EmitterContext = {
   namespace: 'workos',
   namespacePascal: 'WorkOS',
   spec: emptySpec,
-  irVersion: 6,
 };
 
 describe('generateEnums', () => {

package/test/node/errors.test.ts

@@ -1,26 +1,9 @@
 import { describe, it, expect } from 'vitest';
 import { generateErrors } from '../../src/node/errors.js';
-import type { EmitterContext, ApiSpec } from '@workos/oagen';
-
-const emptySpec: ApiSpec = {
-  name: 'Test',
-  version: '1.0.0',
-  baseUrl: '',
-  services: [],
-  models: [],
-  enums: [],
-};
-
-const ctx: EmitterContext = {
-  namespace: 'workos',
-  namespacePascal: 'WorkOS',
-  spec: emptySpec,
-  irVersion: 6,
-};
 
 describe('generateErrors', () => {
   it('generates all exception classes', () => {
-    const files = generateErrors(ctx);
+    const files = generateErrors();
 
     const names = files.map((f) => f.path);
     expect(names).toContain('src/common/exceptions/bad-request.exception.ts');
@@ -35,7 +18,7 @@ describe('generateErrors', () => {
   });
 
   it('generates NotFoundException with correct status', () => {
-    const files = generateErrors(ctx);
+    const files = generateErrors();
     const notFoundFile = files.find((f) => f.path.includes('not-found.exception.ts'))!;
 
     expect(notFoundFile.content).toContain('export class NotFoundException extends Error');
@@ -44,7 +27,7 @@ describe('generateErrors', () => {
   });
 
   it('generates RateLimitExceededException with retryAfter', () => {
-    const files = generateErrors(ctx);
+    const files = generateErrors();
     const rateLimitFile = files.find((f) => f.path.includes('rate-limit-exceeded.exception.ts'))!;
 
     expect(rateLimitFile.content).toContain('export class RateLimitExceededException extends Error');
@@ -53,7 +36,7 @@ describe('generateErrors', () => {
   });
 
   it('generates exception barrel with all exports', () => {
-    const files = generateErrors(ctx);
+    const files = generateErrors();
     const barrel = files.find((f) => f.path === 'src/common/exceptions/index.ts')!;
 
     expect(barrel.content).toContain('export { BadRequestException }');

package/test/node/models.test.ts

@@ -15,7 +15,6 @@ const ctx: EmitterContext = {
   namespace: 'workos',
   namespacePascal: 'WorkOS',
   spec: emptySpec,
-  irVersion: 6,
 };
 
 describe('generateModels', () => {
@@ -85,7 +84,7 @@ describe('generateModels', () => {
     expect(files[0].content).toContain('export interface Organization {');
     expect(files[0].content).toContain('  id: string;');
     expect(files[0].content).toContain('  name: string;');
-    expect(files[0].content).toContain('  createdAt: string;');
+    expect(files[0].content).toContain('  createdAt: Date;');
     expect(files[0].content).toContain('  externalId?: string | null;');
 
     // Response interface has snake_case fields
@@ -298,4 +297,412 @@ describe('generateModels', () => {
     // Field with only deprecated gets single-line JSDoc
     expect(content).toContain('  /** @deprecated */');
   });
+
+  it('renders field-level JSDoc from OpenAPI descriptions', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        description: 'An organization in the WorkOS system.',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            description: 'Unique identifier for the organization.',
+          },
+          {
+            name: 'name',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            description: 'The display name of the organization.',
+          },
+          {
+            name: 'created_at',
+            type: { kind: 'primitive', type: 'string', format: 'date-time' },
+            required: true,
+            // No description — should not get JSDoc
+          },
+          {
+            name: 'allow_profiles_outside_organization',
+            type: { kind: 'primitive', type: 'boolean' },
+            required: false,
+            description:
+              'Whether connections within the organization allow profiles\nthat do not have a domain that is verified by the organization.',
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    const content = files[0].content;
+
+    // Model-level JSDoc is emitted
+    expect(content).toContain('/** An organization in the WorkOS system. */');
+
+    // Fields with description get per-field JSDoc
+    expect(content).toContain('/** Unique identifier for the organization. */');
+    expect(content).toContain('/** The display name of the organization. */');
+
+    // Multiline description renders correctly
+    expect(content).toContain(
+      '  /**\n   * Whether connections within the organization allow profiles\n   * that do not have a domain that is verified by the organization.\n   */',
+    );
+
+    // Field without description does NOT get JSDoc
+    const lines = content.split('\n');
+    const createdAtIdx = lines.findIndex((l) => l.includes('createdAt'));
+    expect(createdAtIdx).toBeGreaterThan(0);
+    // The line before createdAt should not be a JSDoc closing tag
+    expect(lines[createdAtIdx - 1].trim()).not.toBe('*/');
+  });
+
+  it('renders readOnly/writeOnly/default annotations', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Organization' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Organization',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            readOnly: true,
+          },
+          {
+            name: 'secret_key',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            writeOnly: true,
+          },
+          {
+            name: 'status',
+            type: { kind: 'primitive', type: 'string' },
+            required: false,
+            default: 'active',
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    const content = files[0].content;
+
+    // readOnly field gets @readonly JSDoc and readonly TS modifier
+    expect(content).toContain('/** @readonly */');
+    expect(content).toContain('  readonly id: string;');
+
+    // writeOnly field gets @writeonly JSDoc
+    expect(content).toContain('/** @writeonly */');
+
+    // default field gets @default JSDoc
+    expect(content).toContain('@default "active"');
+  });
+
+  it('skips per-domain ListMetadata models (Fix #4)', () => {
+    const service: Service = {
+      name: 'Connections',
+      operations: [
+        {
+          name: 'listConnections',
+          httpMethod: 'get',
+          path: '/connections',
+          pathParams: [],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'ConnectionList' },
+          errors: [],
+          injectIdempotencyKey: false,
+          pagination: {
+            strategy: 'cursor',
+            param: 'after',
+            itemType: { kind: 'model', name: 'Connection' },
+          },
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'ConnectionListListMetadata',
+        fields: [
+          {
+            name: 'before',
+            type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } },
+            required: false,
+          },
+          {
+            name: 'after',
+            type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } },
+            required: false,
+          },
+        ],
+      },
+      {
+        name: 'Connection',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+
+    // The ListMetadata model should be skipped entirely
+    const listMetadataFile = files.find((f) => f.path.includes('list-metadata'));
+    expect(listMetadataFile).toBeUndefined();
+
+    // The Connection model should still be generated
+    const connectionFile = files.find((f) => f.path.includes('connection.interface.ts'));
+    expect(connectionFile).toBeDefined();
+  });
+
+  it('skips per-domain list wrapper models (Fix #6)', () => {
+    const service: Service = {
+      name: 'Connections',
+      operations: [
+        {
+          name: 'listConnections',
+          httpMethod: 'get',
+          path: '/connections',
+          pathParams: [],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'ConnectionList' },
+          errors: [],
+          injectIdempotencyKey: false,
+          pagination: {
+            strategy: 'cursor',
+            param: 'after',
+            itemType: { kind: 'model', name: 'Connection' },
+          },
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'ConnectionList',
+        fields: [
+          {
+            name: 'object',
+            type: { kind: 'literal', value: 'list' },
+            required: true,
+          },
+          {
+            name: 'data',
+            type: { kind: 'array', items: { kind: 'model', name: 'Connection' } },
+            required: true,
+          },
+          {
+            name: 'list_metadata',
+            type: { kind: 'model', name: 'ConnectionListListMetadata' },
+            required: true,
+          },
+        ],
+      },
+      {
+        name: 'ConnectionListListMetadata',
+        fields: [
+          {
+            name: 'before',
+            type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } },
+            required: false,
+          },
+          {
+            name: 'after',
+            type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } },
+            required: false,
+          },
+        ],
+      },
+      {
+        name: 'Connection',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+
+    // The list wrapper model should be skipped
+    const listFile = files.find((f) => f.path.includes('connection-list.interface.ts'));
+    expect(listFile).toBeUndefined();
+
+    // The ListMetadata model should also be skipped
+    const listMetadataFile = files.find((f) => f.path.includes('list-metadata'));
+    expect(listMetadataFile).toBeUndefined();
+
+    // The Connection model should still be generated
+    const connectionFile = files.find((f) => f.path.includes('connection.interface.ts'));
+    expect(connectionFile).toBeDefined();
+  });
+
+  it('does not skip models that only partially match list-metadata shape', () => {
+    const service: Service = {
+      name: 'Organizations',
+      operations: [
+        {
+          name: 'getOrganization',
+          httpMethod: 'get',
+          path: '/organizations/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'Pagination' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'Pagination',
+        fields: [
+          {
+            name: 'before',
+            type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } },
+            required: false,
+          },
+          {
+            name: 'after',
+            type: { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } },
+            required: false,
+          },
+          {
+            name: 'total',
+            type: { kind: 'primitive', type: 'integer' },
+            required: true,
+          },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    // Model with 3 fields should NOT be skipped even if it has before/after
+    expect(files.length).toBe(1);
+    expect(files[0].path).toContain('pagination.interface.ts');
+  });
+});
+
+describe('model deduplication', () => {
+  it('emits type alias for structurally identical models', () => {
+    const service: Service = {
+      name: 'Roles',
+      operations: [
+        {
+          name: 'getRole',
+          httpMethod: 'get',
+          path: '/roles/{id}',
+          pathParams: [{ name: 'id', type: { kind: 'primitive', type: 'string' }, required: true }],
+          queryParams: [],
+          headerParams: [],
+          response: { kind: 'model', name: 'EnvironmentRole' },
+          errors: [],
+          injectIdempotencyKey: false,
+        },
+      ],
+    };
+
+    const models: Model[] = [
+      {
+        name: 'EnvironmentRole',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'type', type: { kind: 'literal', value: 'environment_role' }, required: true },
+        ],
+      },
+      {
+        name: 'OrganizationRole',
+        fields: [
+          { name: 'id', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'name', type: { kind: 'primitive', type: 'string' }, required: true },
+          { name: 'type', type: { kind: 'literal', value: 'environment_role' }, required: true },
+        ],
+      },
+    ];
+
+    const ctxWithServices: EmitterContext = {
+      ...ctx,
+      spec: { ...emptySpec, services: [service], models },
+    };
+
+    const files = generateModels(models, ctxWithServices);
+    expect(files.length).toBe(2);
+
+    // First model: full interface
+    expect(files[0].content).toContain('export interface EnvironmentRole');
+
+    // Second model: type alias referencing canonical
+    expect(files[1].content).toContain('export type OrganizationRole = EnvironmentRole');
+    expect(files[1].content).toContain('export type OrganizationRoleResponse = EnvironmentRoleResponse');
+  });
 });

package/test/node/naming.test.ts

@@ -112,7 +112,6 @@ describe('naming', () => {
         namespace: 'workos',
         namespacePascal: 'WorkOS',
         spec: emptySpec,
-        irVersion: 6,
         overlayLookup: {
           methodByOperation: new Map([
             [
@@ -142,7 +141,6 @@ describe('naming', () => {
         namespace: 'workos',
         namespacePascal: 'WorkOS',
         spec: emptySpec,
-        irVersion: 6,
       };
 
       expect(resolveServiceName(service, ctx)).toBe('MultiFactorAuth');
@@ -187,7 +185,6 @@ describe('naming', () => {
         namespace: 'workos',
         namespacePascal: 'WorkOS',
         spec: emptySpec,
-        irVersion: 6,
         overlayLookup: {
           methodByOperation: new Map([
             [