feat(client): add withOptions helper

Author: stainless-app[bot]

src/client.ts

@@ -171,6 +171,23 @@ export class Stainless {
     this.apiKey = apiKey;
   }
 
+  /**
+   * Create a new client instance re-using the same options given to the current client with optional overriding.
+   */
+  withOptions(options: Partial<ClientOptions>): this {
+    return new (this.constructor as any as new (props: ClientOptions) => typeof this)({
+      ...this._options,
+      baseURL: this.baseURL,
+      maxRetries: this.maxRetries,
+      timeout: this.timeout,
+      logger: this.logger,
+      logLevel: this.logLevel,
+      fetchOptions: this.fetchOptions,
+      apiKey: this.apiKey,
+      ...options,
+    });
+  }
+
   protected defaultQuery(): Record<string, string | undefined> | undefined {
     return this._options.defaultQuery;
   }

tests/index.test.ts

@@ -325,6 +325,82 @@ describe('instantiate client', () => {
     expect(client2.maxRetries).toEqual(2);
   });
 
+  describe('withOptions', () => {
+    test('creates a new client with overridden options', () => {
+      const client = new Stainless({
+        baseURL: 'http://localhost:5000/',
+        maxRetries: 3,
+        apiKey: 'My API Key',
+      });
+
+      const newClient = client.withOptions({
+        maxRetries: 5,
+        baseURL: 'http://localhost:5001/',
+      });
+
+      // Verify the new client has updated options
+      expect(newClient.maxRetries).toEqual(5);
+      expect(newClient.baseURL).toEqual('http://localhost:5001/');
+
+      // Verify the original client is unchanged
+      expect(client.maxRetries).toEqual(3);
+      expect(client.baseURL).toEqual('http://localhost:5000/');
+
+      // Verify it's a different instance
+      expect(newClient).not.toBe(client);
+      expect(newClient.constructor).toBe(client.constructor);
+    });
+
+    test('inherits options from the parent client', () => {
+      const client = new Stainless({
+        baseURL: 'http://localhost:5000/',
+        defaultHeaders: { 'X-Test-Header': 'test-value' },
+        defaultQuery: { 'test-param': 'test-value' },
+        apiKey: 'My API Key',
+      });
+
+      const newClient = client.withOptions({
+        baseURL: 'http://localhost:5001/',
+      });
+
+      // Test inherited options remain the same
+      expect(newClient.buildURL('/foo', null)).toEqual('http://localhost:5001/foo?test-param=test-value');
+
+      const { req } = newClient.buildRequest({ path: '/foo', method: 'get' });
+      expect(req.headers.get('x-test-header')).toEqual('test-value');
+    });
+
+    test('respects runtime property changes when creating new client', () => {
+      const client = new Stainless({
+        baseURL: 'http://localhost:5000/',
+        timeout: 1000,
+        apiKey: 'My API Key',
+      });
+
+      // Modify the client properties directly after creation
+      client.baseURL = 'http://localhost:6000/';
+      client.timeout = 2000;
+
+      // Create a new client with withOptions
+      const newClient = client.withOptions({
+        maxRetries: 10,
+      });
+
+      // Verify the new client uses the updated properties, not the original ones
+      expect(newClient.baseURL).toEqual('http://localhost:6000/');
+      expect(newClient.timeout).toEqual(2000);
+      expect(newClient.maxRetries).toEqual(10);
+
+      // Original client should still have its modified properties
+      expect(client.baseURL).toEqual('http://localhost:6000/');
+      expect(client.timeout).toEqual(2000);
+      expect(client.maxRetries).not.toEqual(10);
+
+      // Verify URL building uses the updated baseURL
+      expect(newClient.buildURL('/bar', null)).toEqual('http://localhost:6000/bar');
+    });
+  });
+
   test('with environment variable arguments', () => {
     // set options via env var
     process.env['API_KEY'] = 'My API Key';