@lokalise/api-contracts 5.2.0 → 5.4.0

package/README.md

@@ -63,3 +63,63 @@ Note that in order to make contract-based requests, you need to use a compatible
 (`@lokalise/frontend-http-client` or `@lokalise/backend-http-client`)
 
 In case you are using fastify on the backend, you can also use `@lokalise/fastify-api-contracts` in order to simplify definition of your fastify routes, utilizing contracts as the single source of truth.
+
+## Utility Functions
+
+### `mapRouteToPath`
+
+Converts a route definition to its corresponding path pattern with parameter placeholders.
+
+```ts
+import { mapRouteToPath, buildGetRoute } from '@lokalise/api-contracts'
+
+const userContract = buildGetRoute({
+    requestPathParamsSchema: z.object({ userId: z.string() }),
+    successResponseBodySchema: USER_SCHEMA,
+    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
+})
+
+const pathPattern = mapRouteToPath(userContract)
+// Returns: "/users/:userId"
+```
+
+This function is useful when you need to:
+- Generate OpenAPI/Swagger documentation
+- Create route patterns for server-side routing frameworks
+- Display route information in debugging or logging
+
+The function replaces actual path parameters with placeholder syntax (`:paramName`), making it compatible with Express-style route patterns.
+
+### `describeContract`
+
+Generates a human-readable description of a route contract, combining the HTTP method with the route path.
+
+```ts
+import { describeContract, buildGetRoute, buildPayloadRoute } from '@lokalise/api-contracts'
+
+const getContract = buildGetRoute({
+    requestPathParamsSchema: z.object({ userId: z.string() }),
+    successResponseBodySchema: USER_SCHEMA,
+    pathResolver: (pathParams) => `/users/${pathParams.userId}`,
+})
+
+const postContract = buildPayloadRoute({
+    method: 'post',
+    requestPathParamsSchema: z.object({ 
+        orgId: z.string(),
+        userId: z.string() 
+    }),
+    requestBodySchema: CREATE_USER_SCHEMA,
+    successResponseBodySchema: USER_SCHEMA,
+    pathResolver: (pathParams) => `/orgs/${pathParams.orgId}/users/${pathParams.userId}`,
+})
+
+console.log(describeContract(getContract))  // "GET /users/:userId"
+console.log(describeContract(postContract)) // "POST /orgs/:orgId/users/:userId"
+```
+
+This function is particularly useful for:
+- Logging and debugging API calls
+- Generating documentation or route summaries
+- Error messages that need to reference specific endpoints
+- Test descriptions and assertions

package/dist/apiContracts.d.ts

@@ -1,6 +1,5 @@
 import type { ZodSchema, z } from 'zod/v4';
 import type { HttpStatusCode } from './HttpStatusCodes.ts';
-export type { HttpStatusCode };
 export type InferSchemaInput<T extends ZodSchema | undefined> = T extends ZodSchema ? z.input<T> : T extends undefined ? undefined : never;
 export type InferSchemaOutput<T extends ZodSchema | undefined> = T extends ZodSchema ? z.infer<T> : T extends undefined ? undefined : never;
 export type RoutePathResolver<PathParams> = (pathParams: PathParams) => string;
@@ -37,3 +36,4 @@ export declare function buildDeleteRoute<SuccessResponseBodySchema extends z.Sch
  * This method maps given route definition to a string of the format '/static-path-part/:path-param-value'
  */
 export declare function mapRouteToPath(routeDefinition: CommonRouteDefinition<any, any, any, any, any, any, any>): string;
+export declare function describeContract(contract: PayloadRouteDefinition<any, any, any, any, any, any, any, any> | GetRouteDefinition<any, any, any, any, any, any, any> | DeleteRouteDefinition<any, any, any, any, any, any, any>): string;

package/dist/apiContracts.js

@@ -67,4 +67,7 @@ routeDefinition) {
     }
     return routeDefinition.pathResolver(resolverParams);
 }
+export function describeContract(contract) {
+    return `${contract.method.toUpperCase()} ${mapRouteToPath(contract)}`;
+}
 //# sourceMappingURL=apiContracts.js.map

package/dist/apiContracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"apiContracts.js","sourceRoot":"","sources":["../src/apiContracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"apiContracts.js","sourceRoot":"","sources":["../src/apiContracts.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './apiContracts.ts';
+export * from './HttpStatusCodes.ts';
+export * from './pathUtils.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./apiContracts.js";
+export * from "./HttpStatusCodes.js";
+export * from "./pathUtils.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAA;AACjC,cAAc,sBAAsB,CAAA;AACpC,cAAc,gBAAgB,CAAA"}

package/dist/pathUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Builds a request path by combining a base path with an optional path prefix.
+ * Ensures proper slash handling to avoid double slashes or missing slashes.
+ *
+ * @param path - The base path for the request
+ * @param pathPrefix - Optional prefix to prepend to the path
+ * @returns The combined path with proper slash formatting
+ *
+ * @example
+ * ```typescript
+ * buildRequestPath('/api/users') // '/api/users'
+ * buildRequestPath('api/users') // '/api/users'
+ * buildRequestPath('/api/users', 'v1') // '/v1/api/users'
+ * buildRequestPath('/api/users', '/v1/') // '/v1/api/users'
+ * buildRequestPath('api/users', 'v1') // '/v1/api/users'
+ * ```
+ */
+export declare function buildRequestPath(path: string, pathPrefix?: string): string;

package/dist/pathUtils.js

@@ -0,0 +1,30 @@
+/**
+ * Builds a request path by combining a base path with an optional path prefix.
+ * Ensures proper slash handling to avoid double slashes or missing slashes.
+ *
+ * @param path - The base path for the request
+ * @param pathPrefix - Optional prefix to prepend to the path
+ * @returns The combined path with proper slash formatting
+ *
+ * @example
+ * ```typescript
+ * buildRequestPath('/api/users') // '/api/users'
+ * buildRequestPath('api/users') // '/api/users'
+ * buildRequestPath('/api/users', 'v1') // '/v1/api/users'
+ * buildRequestPath('/api/users', '/v1/') // '/v1/api/users'
+ * buildRequestPath('api/users', 'v1') // '/v1/api/users'
+ * ```
+ */
+export function buildRequestPath(path, pathPrefix) {
+    if (!pathPrefix) {
+        return ensureStartsWithSlash(path);
+    }
+    // Remove trailing slash from pathPrefix and leading slash from path
+    const cleanPrefix = pathPrefix.endsWith('/') ? pathPrefix.slice(0, -1) : pathPrefix;
+    const cleanPath = path.startsWith('/') ? path.slice(1) : path;
+    return ensureStartsWithSlash(`${cleanPrefix}/${cleanPath}`);
+}
+function ensureStartsWithSlash(str) {
+    return str.startsWith('/') ? str : `/${str}`;
+}
+//# sourceMappingURL=pathUtils.js.map

package/dist/pathUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathUtils.js","sourceRoot":"","sources":["../src/pathUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY,EAAE,UAAmB;IAChE,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC;IAED,oEAAoE;IACpE,MAAM,WAAW,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAA;IACnF,MAAM,SAAS,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAE7D,OAAO,qBAAqB,CAAC,GAAG,WAAW,IAAI,SAAS,EAAE,CAAC,CAAA;AAC7D,CAAC;AAED,SAAS,qBAAqB,CAAC,GAAW;IACxC,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAA;AAC9C,CAAC"}

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "@lokalise/api-contracts",
-    "version": "5.2.0",
+    "version": "5.4.0",
     "files": [
         "dist"
     ],
     "license": "Apache-2.0",
     "type": "module",
-    "main": "./dist/apiContracts.js",
+    "main": "./dist/index.js",
     "enableTransparentWorkspaces": "false",
     "homepage": "https://github.com/lokalise/shared-ts-libs",
     "repository": {
@@ -14,7 +14,7 @@
         "url": "git://github.com/lokalise/shared-ts-libs.git"
     },
     "exports": {
-        ".": "./dist/apiContracts.js",
+        ".": "./dist/index.js",
         "./package.json": "./package.json"
     },
     "private": false,