@workos/oagen-emitters 0.11.0 → 0.12.1

package/src/rust/type-map.ts

@@ -0,0 +1,225 @@
+import type { TypeRef, UnionType } from '@workos/oagen';
+import { typeName } from './naming.js';
+
+/**
+ * Lightweight registry that synthesises a named Rust enum for every IR union
+ * encountered in field positions. Models reference the synthesised name; the
+ * generator emits the enum bodies into a separate module so the crate stays
+ * self-contained.
+ */
+export class UnionRegistry {
+  private byKey = new Map<
+    string,
+    { name: string; tag?: string; arms: { name: string; type: string; rename?: string }[] }
+  >();
+  private hintCounts = new Map<string, number>();
+
+  /** Total number of registered unions (used by callers to skip emit). */
+  size(): number {
+    return this.byKey.size;
+  }
+
+  /** Drop all collected unions. Call at the start of every emit run. */
+  reset(): void {
+    this.byKey.clear();
+    this.hintCounts.clear();
+  }
+
+  /**
+   * Register a union and return the Rust type name to reference.  Unions with
+   * identical structure (same variants + discriminator) are deduplicated.
+   */
+  register(union: UnionType, hint: string): string {
+    const variants = arms(union);
+
+    // Apply discriminator mapping (`{spec-value: '#/components/schemas/Foo'}`)
+    // as `#[serde(rename = "spec-value")]` on the matching variant. Without
+    // this, serde's tagged-union deserialization expects the discriminator
+    // value to literally equal the Rust variant name, which it never does
+    // when the OAS uses snake/kebab-case spec-side keys.
+    const mapping = union.discriminator?.mapping ?? {};
+    const inverseMapping = new Map<string, string>();
+    for (const [specKey, ref] of Object.entries(mapping)) {
+      const schemaName = ref.replace(/^#\/components\/schemas\//, '');
+      // Last value wins — matches spec semantics where the final mapping for
+      // a schema is canonical.
+      inverseMapping.set(typeName(schemaName), specKey);
+    }
+    const armsWithRename: { name: string; type: string; rename?: string }[] = variants.map((v) => {
+      const rename = inverseMapping.get(v.name);
+      return rename !== undefined ? { ...v, rename } : v;
+    });
+
+    const key = JSON.stringify({
+      variants: armsWithRename.map((v) => ({ type: v.type, rename: v.rename ?? null })),
+      discriminator: union.discriminator?.property ?? null,
+      mapping: union.discriminator?.mapping ?? null,
+    });
+    const existing = this.byKey.get(key);
+    if (existing) return existing.name;
+
+    const name = this.uniqueName(`${typeName(hint)}OneOf`);
+    this.byKey.set(key, {
+      name,
+      tag: union.discriminator?.property,
+      arms: armsWithRename,
+    });
+    return name;
+  }
+
+  /**
+   * Render every registered union as a Rust source file (including a leading
+   * `use serde::...;` line).
+   */
+  render(): string {
+    if (this.byKey.size === 0) return '';
+    const blocks: string[] = [];
+    blocks.push('#[allow(unused_imports)]');
+    blocks.push('use super::*;');
+    blocks.push('#[allow(unused_imports)]');
+    blocks.push('use crate::enums::*;');
+    blocks.push('use serde::{Deserialize, Serialize};');
+    blocks.push('');
+
+    for (const u of this.byKey.values()) {
+      blocks.push('#[derive(Debug, Clone, Serialize, Deserialize)]');
+      if (u.tag) {
+        blocks.push(`#[serde(tag = ${JSON.stringify(u.tag)})]`);
+      } else {
+        blocks.push('#[serde(untagged)]');
+      }
+      blocks.push(`pub enum ${u.name} {`);
+      for (const a of u.arms) {
+        if (a.rename !== undefined) {
+          blocks.push(`    #[serde(rename = ${JSON.stringify(a.rename)})]`);
+        }
+        const single = `    ${a.name}(${a.type}),`;
+        if (single.length <= 100) {
+          blocks.push(single);
+        } else {
+          // Match rustfmt's break-shape for over-long tuple variants:
+          //   Variant(
+          //       LongType,
+          //   ),
+          blocks.push(`    ${a.name}(`);
+          blocks.push(`        ${a.type},`);
+          blocks.push('    ),');
+        }
+      }
+      blocks.push('}');
+      blocks.push('');
+    }
+
+    return blocks.join('\n').replace(/\n+$/g, '\n');
+  }
+
+  private uniqueName(base: string): string {
+    const taken = new Set(Array.from(this.byKey.values()).map((u) => u.name));
+    if (!taken.has(base)) return base;
+    const n = (this.hintCounts.get(base) ?? 1) + 1;
+    this.hintCounts.set(base, n);
+    return `${base}${n}`;
+  }
+}
+
+/**
+ * Map an IR `TypeRef` to a Rust type expression (e.g., `String`, `Vec<u32>`,
+ * `Option<HashMap<String, serde_json::Value>>`).
+ *
+ * The caller decides whether to wrap the result in `Option<...>` based on the
+ * field's `required` flag — `mapTypeRef` itself only emits `Option` for the
+ * `nullable` IR variant.
+ *
+ * When `ctx.registry` is supplied, encountered unions are registered as
+ * synthesised Rust enums (using `ctx.hint` to name the generated type); when
+ * no registry is provided, unions degrade to `serde_json::Value`.
+ */
+export function mapTypeRef(ref: TypeRef, ctx?: { hint?: string; registry?: UnionRegistry }): string {
+  switch (ref.kind) {
+    case 'primitive':
+      return primitiveType(ref.type, ref.format);
+    case 'array':
+      return `Vec<${mapTypeRef(ref.items, ctx)}>`;
+    case 'model':
+      return typeName(ref.name);
+    case 'enum':
+      return typeName(ref.name);
+    case 'nullable':
+      return `Option<${mapTypeRef(ref.inner, ctx)}>`;
+    case 'literal':
+      return literalType(ref.value);
+    case 'map':
+      return `std::collections::HashMap<String, ${mapTypeRef(ref.valueType, ctx)}>`;
+    case 'union': {
+      const variants = ref.variants;
+      const mapped = variants.map((v) => mapTypeRef(v, ctx));
+      const unique = Array.from(new Set(mapped));
+      if (unique.length === 1) return unique[0]!;
+      if (ctx?.registry && ctx.hint) {
+        return ctx.registry.register(ref, ctx.hint);
+      }
+      return 'serde_json::Value';
+    }
+  }
+}
+
+/** Variants for the registry: each gets a Rust variant name + a payload type. */
+function arms(union: UnionType): { name: string; type: string }[] {
+  const seen = new Set<string>();
+  const out: { name: string; type: string }[] = [];
+  for (const v of union.variants) {
+    const t = mapTypeRef(v); // No registry — variants must already be named.
+    const armName = variantArmName(v, t);
+    let unique = armName;
+    let n = 1;
+    while (seen.has(unique)) {
+      n += 1;
+      unique = `${armName}${n}`;
+    }
+    seen.add(unique);
+    out.push({ name: unique, type: t });
+  }
+  return out;
+}
+
+function variantArmName(ref: TypeRef, mappedType: string): string {
+  if (ref.kind === 'model' || ref.kind === 'enum') return typeName(ref.name);
+  // Strip generics for arm naming and PascalCase.
+  const base = mappedType.replace(/[<>:,\s]/g, '');
+  return typeName(base);
+}
+
+/**
+ * Wrap a type in `Option<...>` if not already optional. Used for non-required
+ * fields where the IR did not produce a `nullable` wrapper.
+ */
+export function makeOptional(rustType: string): string {
+  if (rustType.startsWith('Option<')) return rustType;
+  return `Option<${rustType}>`;
+}
+
+function primitiveType(type: 'string' | 'integer' | 'number' | 'boolean' | 'unknown', format?: string): string {
+  switch (type) {
+    case 'string':
+      if (format === 'binary') return 'Vec<u8>';
+      return 'String';
+    case 'integer':
+      if (format === 'int32') return 'i32';
+      return 'i64';
+    case 'number':
+      if (format === 'float') return 'f32';
+      return 'f64';
+    case 'boolean':
+      return 'bool';
+    case 'unknown':
+      return 'serde_json::Value';
+  }
+}
+
+function literalType(value: string | number | boolean | null): string {
+  if (value === null) return 'serde_json::Value';
+  if (typeof value === 'string') return 'String';
+  if (typeof value === 'number') return Number.isInteger(value) ? 'i64' : 'f64';
+  if (typeof value === 'boolean') return 'bool';
+  return 'serde_json::Value';
+}

package/test/entrypoint.test.ts

@@ -60,6 +60,7 @@ describe('public entrypoint (@workos/oagen-emitters)', () => {
       mod.dotnetEmitter,
       mod.kotlinEmitter,
       mod.rubyEmitter,
+      mod.rustEmitter,
     ];
     for (const emitter of directEmitters) {
       expect(pluginLanguages).toContain(emitter.language);

package/test/plugin.test.ts

@@ -11,7 +11,8 @@ describe('workosEmittersPlugin', () => {
     expect(languages).toContain('dotnet');
     expect(languages).toContain('kotlin');
     expect(languages).toContain('ruby');
-    expect(languages).toHaveLength(7);
+    expect(languages).toContain('rust');
+    expect(languages).toHaveLength(8);
   });
 
   it('exports extractors for all supported languages', () => {

package/test/python/resources.test.ts

@@ -83,8 +83,8 @@ describe('generateResources', () => {
     // GET method with path param
     expect(content).toContain('def get_organization(');
     expect(content).toContain('id: str,');
-    expect(content).toContain(`f"organizations/{quote(str(id), safe='')}"`);
-    expect(content).toContain('from urllib.parse import quote');
+    expect(content).toContain(`("organizations", str(id))`);
+    expect(content).not.toContain('from urllib.parse import quote');
     expect(content).toContain('model=Organization');
     // Public request methods (no underscore prefix)
     expect(content).toContain('self._client.request(');

package/test/rust/client.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import type { EmitterContext, ApiSpec, Model } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+import { generateClient } from '../../src/rust/client.js';
+import { generateModels } from '../../src/rust/models.js';
+import { UnionRegistry } from '../../src/rust/type-map.js';
+
+function makeCtx(spec: ApiSpec): EmitterContext {
+  return { namespace: 'workos', namespacePascal: 'WorkOS', spec };
+}
+
+const emptySpec: ApiSpec = {
+  name: 'Test',
+  version: '1.0.0',
+  baseUrl: '',
+  services: [],
+  models: [],
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+describe('rust/client', () => {
+  it('emits the unions module and an empty resources_api shell when there are no mount targets', () => {
+    const files = generateClient(emptySpec, makeCtx(emptySpec), new UnionRegistry());
+    expect(files.map((f) => f.path).sort()).toEqual(['src/models/_unions.rs', 'src/resources_api.rs']);
+    const unions = files.find((f) => f.path === 'src/models/_unions.rs')!;
+    expect(unions.content).toContain('No oneOf-style unions registered');
+    const api = files.find((f) => f.path === 'src/resources_api.rs')!;
+    expect(api.content).toContain('impl Client {');
+  });
+
+  it('renders unions registered earlier in the emit run', () => {
+    const registry = new UnionRegistry();
+    const models: Model[] = [
+      {
+        name: 'Event',
+        fields: [
+          {
+            name: 'payload',
+            type: {
+              kind: 'union',
+              variants: [
+                { kind: 'model', name: 'UserCreated' },
+                { kind: 'model', name: 'UserDeleted' },
+              ],
+              discriminator: {
+                property: 'event',
+                mapping: { 'user.created': 'UserCreated', 'user.deleted': 'UserDeleted' },
+              },
+            },
+            required: true,
+          },
+        ],
+      },
+    ];
+    generateModels(models, makeCtx(emptySpec), registry);
+    const files = generateClient(emptySpec, makeCtx(emptySpec), registry);
+    const unions = files.find((f) => f.path === 'src/models/_unions.rs')!;
+    expect(unions.content).toContain('#[serde(tag = "event")]');
+    expect(unions.content).toContain('pub enum EventPayloadOneOf {');
+  });
+});

package/test/rust/enums.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import type { EmitterContext, ApiSpec, Enum } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+import { generateEnums } from '../../src/rust/enums.js';
+
+const emptySpec: ApiSpec = {
+  name: 'Test',
+  version: '1.0.0',
+  baseUrl: '',
+  services: [],
+  models: [],
+  enums: [],
+  sdk: defaultSdkBehavior(),
+};
+
+const ctx: EmitterContext = {
+  namespace: 'workos',
+  namespacePascal: 'WorkOS',
+  spec: emptySpec,
+};
+
+describe('rust/enums', () => {
+  it('emits a non_exhaustive enum with manual Serialize/Deserialize and a fallback variant', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Status',
+        values: [
+          { name: 'active', value: 'active' },
+          { name: 'inactive', value: 'inactive' },
+        ],
+      },
+    ];
+    const files = generateEnums(enums, ctx);
+    const f = files.find((x) => x.path === 'src/enums/status.rs')!;
+    expect(f.content).toContain('pub enum Status {');
+    expect(f.content).toContain('Active,');
+    expect(f.content).toContain('Inactive,');
+    expect(f.content).toContain('#[non_exhaustive]');
+    expect(f.content).toContain('Unknown(String),');
+    expect(f.content).toContain('impl Serialize for Status');
+    expect(f.content).toContain("impl<'de> Deserialize<'de> for Status");
+    expect(f.content).toContain('Self::Active => "active"');
+    expect(f.content).toContain('Self::Inactive => "inactive"');
+    // No derive(Serialize/Deserialize) — they're hand-written.
+    expect(f.content).not.toContain('Serialize, Deserialize)]');
+  });
+
+  it('round-trips non-snake-case wire values through canonical strings', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Mode',
+        values: [
+          { name: 'kebab-case', value: 'kebab-case' },
+          { name: 'mixedCase', value: 'mixedCase' },
+        ],
+      },
+    ];
+    const files = generateEnums(enums, ctx);
+    const f = files.find((x) => x.path === 'src/enums/mode.rs')!;
+    // FromStr matches the original wire string; as_str returns it back.
+    expect(f.content).toContain('"kebab-case" => Self::KebabCase');
+    expect(f.content).toContain('"mixedCase" => Self::MixedCase');
+    expect(f.content).toContain('Self::KebabCase => "kebab-case"');
+    expect(f.content).toContain('Self::MixedCase => "mixedCase"');
+  });
+
+  it('collapses alias wire values into a single canonical variant', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Trigger',
+        values: [
+          { name: 'sign-up', value: 'sign-up' },
+          { name: 'sign_up', value: 'sign_up' },
+          { name: 'sign up', value: 'sign up' },
+        ],
+      },
+    ];
+    const files = generateEnums(enums, ctx);
+    const f = files.find((x) => x.path === 'src/enums/trigger.rs')!;
+    // One Rust variant for all three aliases.
+    expect(f.content.match(/^\s+SignUp,$/m)).not.toBeNull();
+    // Canonical wire value is the first one seen.
+    expect(f.content).toContain('Self::SignUp => "sign-up"');
+    // Every alias deserializes into the same variant.
+    expect(f.content).toContain('"sign-up" => Self::SignUp');
+    expect(f.content).toContain('"sign_up" => Self::SignUp');
+    expect(f.content).toContain('"sign up" => Self::SignUp');
+  });
+
+  it('falls back to a non-Unknown name when the spec defines an Unknown variant', () => {
+    const enums: Enum[] = [
+      {
+        name: 'State',
+        values: [
+          { name: 'unknown', value: 'unknown' },
+          { name: 'ready', value: 'ready' },
+        ],
+      },
+    ];
+    const files = generateEnums(enums, ctx);
+    const f = files.find((x) => x.path === 'src/enums/state.rs')!;
+    expect(f.content).toContain('Unknown,');
+    expect(f.content).toContain('Unrecognized(String),');
+  });
+
+  it('skips empty enums', () => {
+    const enums: Enum[] = [{ name: 'Empty', values: [] }];
+    const files = generateEnums(enums, ctx);
+    expect(files.find((f) => f.path === 'src/enums/empty.rs')).toBeUndefined();
+  });
+
+  it('always emits a barrel even when no enums', () => {
+    const files = generateEnums([], ctx);
+    expect(files).toHaveLength(1);
+    expect(files[0]!.path).toBe('src/enums/mod.rs');
+  });
+});

package/test/rust/fixtures.test.ts

@@ -0,0 +1,227 @@
+import { describe, it, expect } from 'vitest';
+import type { ApiSpec, Enum, Model } from '@workos/oagen';
+import { defaultSdkBehavior } from '@workos/oagen';
+import { exampleFromSpec, generateFixtures, generateModelFixture } from '../../src/rust/fixtures.js';
+
+function spec(models: Model[], enums: Enum[] = []): ApiSpec {
+  return {
+    name: 'Test',
+    version: '1.0.0',
+    baseUrl: '',
+    services: [],
+    models,
+    enums,
+    sdk: defaultSdkBehavior(),
+  };
+}
+
+describe('rust/fixtures', () => {
+  it('prefers a spec `example` over the generated placeholder for a primitive field', () => {
+    const models: Model[] = [
+      {
+        name: 'Event',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            example: 'event_01XXXX',
+          },
+          {
+            name: 'created_at',
+            type: { kind: 'primitive', type: 'string', format: 'date-time' },
+            required: true,
+            example: '2026-02-02T16:35:39.317Z',
+          },
+        ],
+      },
+    ];
+    const files = generateFixtures(spec(models));
+    const file = files.find((f) => f.path === 'tests/fixtures/event.json')!;
+    expect(file).toBeDefined();
+    const parsed = JSON.parse(file.content);
+    expect(parsed.id).toBe('event_01XXXX');
+    expect(parsed.created_at).toBe('2026-02-02T16:35:39.317Z');
+  });
+
+  it('falls back to the placeholder when the example shape does not match the type', () => {
+    const models: Model[] = [
+      {
+        name: 'Wrong',
+        fields: [
+          // Type is integer but example is a string — must fall back.
+          {
+            name: 'count',
+            type: { kind: 'primitive', type: 'integer' },
+            required: true,
+            example: 'not-a-number',
+          },
+        ],
+      },
+    ];
+    const files = generateFixtures(spec(models));
+    const file = files.find((f) => f.path === 'tests/fixtures/wrong.json')!;
+    const parsed = JSON.parse(file.content);
+    expect(parsed.count).toBe(0); // placeholder fallback
+  });
+
+  it('uses an example array of strings for an array<string> field', () => {
+    const models: Model[] = [
+      {
+        name: 'Org',
+        fields: [
+          {
+            name: 'domains',
+            type: {
+              kind: 'array',
+              items: { kind: 'primitive', type: 'string' },
+            },
+            required: true,
+            example: ['example.com', 'foo.com'],
+          },
+        ],
+      },
+    ];
+    const files = generateFixtures(spec(models));
+    const file = files.find((f) => f.path === 'tests/fixtures/org.json')!;
+    const parsed = JSON.parse(file.content);
+    expect(parsed.domains).toEqual(['example.com', 'foo.com']);
+  });
+
+  it('skips a model-shaped example to avoid mis-shaped nested structs', () => {
+    const models: Model[] = [
+      {
+        name: 'Outer',
+        fields: [
+          {
+            name: 'actor',
+            type: { kind: 'model', name: 'Actor' },
+            required: true,
+            // Provided as a free-form example; we should NOT use it verbatim.
+            example: { not_a_real_field: 'whoops' },
+          },
+        ],
+      },
+      {
+        name: 'Actor',
+        fields: [
+          {
+            name: 'id',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            example: 'user_TF4C5938',
+          },
+          {
+            name: 'type',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            example: 'user',
+          },
+        ],
+      },
+    ];
+    const files = generateFixtures(spec(models));
+    const file = files.find((f) => f.path === 'tests/fixtures/outer.json')!;
+    const parsed = JSON.parse(file.content);
+    // The nested model is regenerated from its own fields' examples, not from
+    // the parent's free-form example blob.
+    expect(parsed.actor).toEqual({ id: 'user_TF4C5938', type: 'user' });
+  });
+
+  it('uses an enum example only when it matches a known enum value', () => {
+    const enums: Enum[] = [
+      {
+        name: 'Status',
+        values: [
+          { name: 'Active', value: 'active' },
+          { name: 'Pending', value: 'pending' },
+        ],
+      },
+    ];
+    const models: Model[] = [
+      {
+        name: 'GoodEx',
+        fields: [
+          {
+            name: 'status',
+            type: { kind: 'enum', name: 'Status' },
+            required: true,
+            example: 'pending',
+          },
+        ],
+      },
+      {
+        name: 'BadEx',
+        fields: [
+          {
+            name: 'status',
+            type: { kind: 'enum', name: 'Status' },
+            required: true,
+            example: 'something_unknown',
+          },
+        ],
+      },
+    ];
+    const files = generateFixtures(spec(models, enums));
+    const good = JSON.parse(files.find((f) => f.path === 'tests/fixtures/good_ex.json')!.content);
+    const bad = JSON.parse(files.find((f) => f.path === 'tests/fixtures/bad_ex.json')!.content);
+    expect(good.status).toBe('pending'); // valid example wins
+    expect(bad.status).toBe('active'); // unknown example → first enum value
+  });
+
+  it('treats null examples as unusable so required fields keep a value', () => {
+    const models: Model[] = [
+      {
+        name: 'Nullish',
+        fields: [
+          {
+            name: 'name',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            example: null,
+          },
+        ],
+      },
+    ];
+    const files = generateFixtures(spec(models));
+    const parsed = JSON.parse(files.find((f) => f.path === 'tests/fixtures/nullish.json')!.content);
+    expect(parsed.name).toBe('test_name');
+  });
+
+  it('exampleFromSpec exposes the shape-checking helper for reuse', () => {
+    const enums = new Map<string, Enum>();
+    // Primitives are unwrapped through nullable.
+    expect(exampleFromSpec('hello', { kind: 'nullable', inner: { kind: 'primitive', type: 'string' } }, enums)).toBe(
+      'hello',
+    );
+    // Integer floats are rejected (they would corrupt typed deserialisation).
+    expect(exampleFromSpec(1.5, { kind: 'primitive', type: 'integer' }, enums)).toBeUndefined();
+    // Empty arrays fall back so the placeholder can emit a one-element array.
+    expect(exampleFromSpec([], { kind: 'array', items: { kind: 'primitive', type: 'string' } }, enums)).toBeUndefined();
+  });
+
+  it('threads required-only field selection through generateModelFixture', () => {
+    const models: Model[] = [
+      {
+        name: 'Mixed',
+        fields: [
+          {
+            name: 'kept',
+            type: { kind: 'primitive', type: 'string' },
+            required: true,
+            example: 'real',
+          },
+          {
+            name: 'dropped',
+            type: { kind: 'primitive', type: 'string' },
+            required: false,
+            example: 'ignored',
+          },
+        ],
+      },
+    ];
+    const modelMap = new Map(models.map((m) => [m.name, m]));
+    const fixture = generateModelFixture(models[0]!, modelMap, new Map(), new Set());
+    expect(fixture).toEqual({ kept: 'real' });
+  });
+});