(feature, typescript): Add offset step pagination with IRv48 (#4028)

generators/typescript/express/CHANGELOG.md

@@ -5,27 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.17.0-rc0] - 2024-06-26
+## [0.17.0] - 2024-07-09
+
+- Internal: Upgrade to IRv48.
+
+## [0.17.0-rc0] - 2024-07-09
 
 - Fix: All serializers in the generated express server are now synchronous. This makes the serializers
-  easier to use and improves the performance as well. 
+  easier to use and improves the performance as well.
 
 ## [0.16.3] - 2024-06-26
 
-- Feature: The Express generator now supports a `requestValidationStatusCode` configuration 
-  where a user can specify the status code that should be thrown when the request doesn't 
-  match schema validation. 
+- Feature: The Express generator now supports a `requestValidationStatusCode` configuration
+  where a user can specify the status code that should be thrown when the request doesn't
+  match schema validation.
 
   ```yaml
   - name: fernapi/fern-typescript-express
     version: 0.16.3
-    config: 
+    config:
       requestValidationStatusCode: 400 # Defaults to 422
   ```
 
 ## [0.16.2] - 2024-06-26
 
-- Internal: The generator is now upgraded to `v46.2.0` of the IR. 
+- Internal: The generator is now upgraded to `v46.2.0` of the IR.
 
 ## [0.16.1] - 2024-06-13
 

generators/typescript/express/VERSION

@@ -1 +1 @@
-0.17.0-rc0
+0.17.0

generators/typescript/express/cli/package.json

@@ -30,7 +30,7 @@
   },
   "devDependencies": {
     "@fern-fern/generator-exec-sdk": "^0.0.898",
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/abstract-generator-cli": "workspace:*",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",

generators/typescript/express/express-endpoint-type-schemas-generator/package.json

@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/abstract-schema-generator": "workspace:*",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",

generators/typescript/express/express-error-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/abstract-error-class-generator": "workspace:*",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",

generators/typescript/express/express-error-schema-generator/package.json

@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/abstract-schema-generator": "workspace:*",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",

generators/typescript/express/express-inlined-request-body-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*"
   },

generators/typescript/express/express-inlined-request-body-schema-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/abstract-schema-generator": "workspace:*",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",

generators/typescript/express/express-register-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",
     "@fern-typescript/resolvers": "workspace:*",

generators/typescript/express/express-service-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",
     "@fern-typescript/resolvers": "workspace:*",

generators/typescript/express/generator/package.json

@@ -28,7 +28,7 @@
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/fs-utils": "workspace:*",
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",
     "@fern-typescript/express-endpoint-type-schemas-generator": "workspace:*",

generators/typescript/model/type-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",
     "@fern-typescript/union-generator": "workspace:*",

generators/typescript/model/type-reference-converters/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/resolvers": "workspace:*",
     "ts-morph": "^15.1.0"

generators/typescript/model/type-reference-example-generator/package.json

@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",
     "ts-morph": "^15.1.0"

generators/typescript/model/type-schema-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/abstract-schema-generator": "workspace:*",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",

generators/typescript/model/union-generator/package.json

@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",
     "ts-morph": "^15.1.0"

generators/typescript/model/union-schema-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/abstract-schema-generator": "workspace:*",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",

generators/typescript/sdk/CHANGELOG.md

@@ -5,10 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.29.0] - 2024-07-09
+
+- Internal: Upgrade to IRv48.
+- Feature: Add support for pagination endpoints that require request body properties.
+- Feature: Add support for pagination with an offset step. This is useful for endpoints
+  that page based on the element index rather than a page index (i.e. the 100th element
+  vs. the 10th page).
+
+  This feature shares the same UX as both the `offset` and `cursor` pagination variants.
+
 ## [0.29.0-rc0] - 2024-07-09
 
 - Fix: All serializers in the generated SDK are now synchronous. This makes the serializers
-  easier to use and improves the performance as well. 
+  easier to use and improves the performance as well.
 
 ## [0.28.0-rc0] - 2024-07-09
 

generators/typescript/sdk/VERSION

@@ -1 +1 @@
-0.29.0-rc0
+0.29.0

generators/typescript/sdk/cli/package.json

@@ -34,7 +34,7 @@
   "devDependencies": {
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/generator-commons": "workspace:*",
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/abstract-generator-cli": "workspace:*",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",

generators/typescript/sdk/client-class-generator/package.json

@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
-    "@fern-fern/ir-sdk": "0.0.3515",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",
     "@fern-typescript/resolvers": "workspace:*",

generators/typescript/sdk/client-class-generator/src/endpoints/default/GeneratedDefaultEndpointImplementation.ts

@@ -118,7 +118,7 @@ export class GeneratedDefaultEndpointImplementation implements GeneratedEndpoint
         }
 
         const examples: string[] = [];
-        for (const example of getExampleEndpointCalls(this.endpoint.examples)) {
+        for (const example of getExampleEndpointCalls(this.endpoint)) {
             const generatedExample = this.getExample({
                 context,
                 example,
@@ -209,7 +209,7 @@ export class GeneratedDefaultEndpointImplementation implements GeneratedEndpoint
                 ts.NodeFlags.Const
             );
             const statements: ts.Statement[] = [ts.factory.createVariableStatement(undefined, listFn)];
-            if (paginationInfo.type === "offset") {
+            if (paginationInfo.type === "offset" || paginationInfo.type === "offset-step") {
                 statements.push(paginationInfo.initializeOffset);
             }
             statements.push(

generators/typescript/sdk/client-class-generator/src/endpoints/default/endpoint-response/GeneratedThrowingEndpointResponse.ts

@@ -172,7 +172,7 @@ export class GeneratedThrowingEndpointResponse implements GeneratedEndpointRespo
                             ts.factory.createSpreadAssignment(ts.factory.createIdentifier("request")),
                             ts.factory.createPropertyAssignment(
                                 ts.factory.createIdentifier(
-                                    this.getNameFromWireValue({ name: cursor.page.name, context })
+                                    this.getNameFromWireValue({ name: cursor.page.property.name, context })
                                 ),
                                 nextPropertyAccess
                             )
@@ -212,8 +212,11 @@ export class GeneratedThrowingEndpointResponse implements GeneratedEndpointRespo
         const itemType = context.type.getReferenceToType(itemTypeReference).typeNode;
 
         // initializeOffset uses the offset property if set
-        const pageProperty = this.getNameFromWireValue({ name: offset.page.name, context });
-        const pagePropertyPath = ["request"].join("?."); // TODO: Add support for nested properties after IR upgrade.
+        const pageProperty = this.getNameFromWireValue({ name: offset.page.property.name, context });
+        const pagePropertyPath = [
+            "request",
+            ...(offset.page.propertyPath ?? []).map((name) => this.getName({ name, context }))
+        ].join("?.");
         const pagePropertyAccess = ts.factory.createPropertyAccessExpression(
             ts.factory.createIdentifier(pagePropertyPath),
             ts.factory.createIdentifier(pageProperty)
@@ -245,10 +248,12 @@ export class GeneratedThrowingEndpointResponse implements GeneratedEndpointRespo
 
         // hasNextPage checks if the items are not empty
         const itemsProperty = this.getNameFromWireValue({ name: offset.results.property.name, context });
-        const itemsPropertyPath = [
+        const itemsPropertyPathComponents = [
             "response",
             ...(offset.results.propertyPath ?? []).map((name) => this.getName({ name, context }))
-        ].join("?.");
+        ];
+        const itemsPropertyPath = itemsPropertyPathComponents.join("?.");
+        const itemsPropertyPathWithoutOptional = itemsPropertyPathComponents.join(".");
         const itemsPropertyAccess = ts.factory.createPropertyAccessChain(
             ts.factory.createIdentifier(itemsPropertyPath),
             ts.factory.createToken(ts.SyntaxKind.QuestionDotToken),
@@ -281,20 +286,51 @@ export class GeneratedThrowingEndpointResponse implements GeneratedEndpointRespo
         );
 
         // loadPage
-        const incrementOffset = ts.factory.createExpressionStatement(
-            ts.factory.createBinaryExpression(
-                ts.factory.createIdentifier("_offset"),
-                ts.factory.createToken(ts.SyntaxKind.PlusEqualsToken),
-                ts.factory.createNumericLiteral("1")
-            )
-        );
+        const incrementOffset =
+            offset.step != null
+                ? ts.factory.createExpressionStatement(
+                      ts.factory.createBinaryExpression(
+                          ts.factory.createIdentifier("_offset"),
+                          ts.factory.createToken(ts.SyntaxKind.PlusEqualsToken),
+                          ts.factory.createConditionalExpression(
+                              ts.factory.createBinaryExpression(
+                                  itemsPropertyAccess,
+                                  ts.factory.createToken(ts.SyntaxKind.ExclamationEqualsToken),
+                                  ts.factory.createNull()
+                              ),
+                              ts.factory.createToken(ts.SyntaxKind.QuestionToken),
+                              ts.factory.createBinaryExpression(
+                                  ts.factory.createPropertyAccessExpression(
+                                      ts.factory.createPropertyAccessExpression(
+                                          ts.factory.createIdentifier(itemsPropertyPathWithoutOptional),
+                                          ts.factory.createIdentifier(itemsProperty)
+                                      ),
+                                      ts.factory.createIdentifier("length")
+                                  ),
+                                  ts.factory.createToken(ts.SyntaxKind.PlusToken),
+                                  ts.factory.createNumericLiteral("1")
+                              ),
+                              ts.factory.createToken(ts.SyntaxKind.ColonToken),
+                              ts.factory.createNumericLiteral("1")
+                          )
+                      )
+                  )
+                : ts.factory.createExpressionStatement(
+                      ts.factory.createBinaryExpression(
+                          ts.factory.createIdentifier("_offset"),
+                          ts.factory.createToken(ts.SyntaxKind.PlusEqualsToken),
+                          ts.factory.createNumericLiteral("1")
+                      )
+                  );
         const callEndpoint = ts.factory.createReturnStatement(
             ts.factory.createCallExpression(ts.factory.createIdentifier("list"), undefined, [
                 ts.factory.createObjectLiteralExpression(
                     [
                         ts.factory.createSpreadAssignment(ts.factory.createIdentifier("request")),
                         ts.factory.createPropertyAssignment(
-                            ts.factory.createIdentifier(this.getNameFromWireValue({ name: offset.page.name, context })),
+                            ts.factory.createIdentifier(
+                                this.getNameFromWireValue({ name: offset.page.property.name, context })
+                            ),
                             ts.factory.createIdentifier("_offset")
                         )
                     ],
@@ -305,7 +341,7 @@ export class GeneratedThrowingEndpointResponse implements GeneratedEndpointRespo
         const loadPage = [incrementOffset, callEndpoint];
 
         return {
-            type: "offset",
+            type: offset.step != null ? "offset-step" : "offset",
             initializeOffset,
             itemType,
             responseType: successReturnType,

generators/typescript/sdk/endpoint-error-union-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",
     "@fern-typescript/resolvers": "workspace:*",

generators/typescript/sdk/environments-generator/package.json

@@ -26,7 +26,7 @@
     "depcheck": "depcheck"
   },
   "dependencies": {
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",
     "ts-morph": "^15.1.0"

generators/typescript/sdk/generator/package.json

@@ -32,7 +32,7 @@
     "@fern-api/logging-execa": "workspace:*",
     "@fern-fern/generator-cli-sdk": "0.0.56",
     "@fern-fern/generator-exec-sdk": "^0.0.898",
-    "@fern-fern/ir-sdk": "46.2.0",
+    "@fern-fern/ir-sdk": "48.1.0",
     "@fern-fern/snippet-sdk": "^0.0.5492",
     "@fern-typescript/commons": "workspace:*",
     "@fern-typescript/contexts": "workspace:*",

generators/typescript/sdk/generator/src/SdkGenerator.ts

@@ -839,12 +839,16 @@ export class SdkGenerator {
                     }
                 }
 
-                let examplesForEndpoint = endpoint.examples.filter((example) => {
-                    return example.exampleType === "userProvided";
-                });
-                // use a single autogenerated example if no user provided examples
-                if (examplesForEndpoint.length === 0 && endpoint.examples[0] != null) {
-                    examplesForEndpoint = [endpoint.examples[0]];
+                let examplesForEndpoint: ExampleEndpointCall[] = [];
+                for (const userDefinedExample of endpoint.userSpecifiedExamples) {
+                    if (userDefinedExample.example != null) {
+                        examplesForEndpoint.push(userDefinedExample.example);
+                    }
+                }
+                if (examplesForEndpoint.length === 0) {
+                    // use a single autogenerated example if no user provided examples
+                    const maybeAutogeneratedExample = endpoint.autogeneratedExamples[0]?.example;
+                    examplesForEndpoint = maybeAutogeneratedExample != null ? [maybeAutogeneratedExample] : [];
                 }
 
                 for (const example of examplesForEndpoint) {