open-index/open-npm huggingface dataset:
npm package: @flipdish/cdk-constructs
Description: CDK Constructs for Flipdish serverless applications
Author: Flipdish
Latest version: 0.71.0

# @flipdish/cdk-constructs

CDK Constructs for Flipdish serverless applications, with a focus on API constructs that provide automatic OpenAPI documentation generation and deployment.

## Installation

```bash
npm install @flipdish/cdk-constructs
```

## Overview

This package provides CDK constructs and utilities for building serverless APIs with strong typing and automatic OpenAPI documentation. It is designed to be used with [SST](https://sst.dev/) and integrates with Zod for schema validation and OpenAPI generation.

## Features

- **Api Construct**: Drop-in replacement for SST's Api construct, with built-in OpenAPI documentation generation.
- **Automatic OpenAPI Docs**: Generates and deploys OpenAPI JSON, YAML, and HTML documentation for your API routes.
- **Schema Integration**: Supports Zod-based schema definitions for routes.
- **TypeScript-first**: All constructs and utilities are strictly typed.

## Usage

### Basic Example

```typescript
import { Api, SchemaFunction } from '@flipdish/cdk-constructs';
import { z } from 'zod';
import { StackContext } from 'sst/constructs';

export function API({ stack }: StackContext) {
  const api = new Api(stack, 'Api', {
    routes: {
      'GET /hello': {
        function: new SchemaFunction(stack, 'HelloHandler', {
          handler: 'src/hello.handler',
          schema: {
            responses: {
              200: z.object({ message: z.string() }),
            },
          },
        }),
      },
    },
  });

  // The following endpoints are automatically added:
  // - /openapi.json
  // - /openapi.yaml
  // - /openapi.html

  return { api };
}
```

### OpenAPI Utilities

You can also use the following utilities for advanced OpenAPI schema generation:

- `buildSchema(registry, serviceName, url)`: Generates an OpenAPI schema document from a registry.
- `sstRoutesToOpenApiSchema(routes)`: Converts SST route definitions to OpenAPI route configs.

### Types

The package exports several types to help with strong typing and schema integration:

- `Schema`
- `SchemaFunction`
- `SchemaFunctionProps`
- `SchemaRouteProps`
- `SchemaApiProps`
- `SchemaApiFunctionRouteProps`

## Development & Testing

This package is maintained in the [serverless-app-template](https://github.com/flipdishbytes/serverless-app-template) repository.

### Testing

You can test the constructs by deploying a stack and verifying that the OpenAPI documentation endpoints are available and accurate. For unit testing, use your preferred test runner (e.g., Vitest or Jest) to check that the constructs behave as expected.

## License

MIT

## Contributing

This package is maintained in the [serverless-app-template](https://github.com/flipdishbytes/serverless-app-template) repository.