Skip to content

Commit

Permalink
temp: update readme except everything after overview
Browse files Browse the repository at this point in the history
  • Loading branch information
Steven Yuan committed Nov 7, 2023
1 parent 707de66 commit d3864eb
Showing 1 changed file with 2 additions and 25 deletions.
27 changes: 2 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,6 @@ By default, the Smithy TypeScript code generators provide the code generation fr
- Protocols: Protocols define how operation shapes (for clients and servers, these are usually inputs and outputs) are serialized and deserialized on the wire. This behavior can be defined in Smithy through [protocol traits](https://smithy.io/2.0/spec/protocol-traits.html) with corresponding implementations of [the `ProtocolGenerator` interface](codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/integration/ProtocolGenerator.java). For example, [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3), a customer of Smithy TypeScript, implements the [AWS protocols](https://smithy.io/2.0/aws/protocols/index.html) in the `software.amazon.smithy.typescript:smithy-aws-typescript-codegen` package. There is [an open issue](https://github.com/aws/smithy-go/issues/458) tracking the movement of these AWS protocols implementations out of the SDK into smithy-go, but there is no currently no timeline fod doing so. See [the section on protocol generator implementations for more details](#protocol-generator-implementations).
- Publishing: There is no idiomatic utility to publish generated artifacts since package distribution can vary depending on different technical requirements. For example, [AWS SDK for JavaScript v3](https://github.com/aws/aws-sdk-js-v3), a customer of Smithy TypeScript, has custom tooling to manage versioning, change logs, and publishing in a monorepo. See [the section on publishing client packages for more details](#publishing-a-client-sdk-package).
- Endpoint resolution (clients): Endpoint resolution is not implemented by default due to a variety of different implementations. In most cases, providing a default provider in the runtime config for the client config `endpoint` property should suffice. More complex use cases include [the `@smithy.rules#endpointRuleSet` trait](https://smithy.io/2.0/additional-specs/rules-engine/specification.html#smithy-rules-endpointruleset-trait) which provides [a complete DSL for endpoint resolution](https://smithy.io/2.0/additional-specs/rules-engine/index.html). See [the section on handling endpoint resolution for more details](#handling-endpoint-resolution).
- Operation handler implementations (servers): The server code generator provides the scaffolding for operations. The operation handlers defining the business logic of the Smithy service need to be implemented manually.

### Client SDK code generation: `typescript-client-codegen` plugin

Expand Down Expand Up @@ -435,30 +434,6 @@ See [the section on customizations via `TypeScriptIntegration` for more details]

A generated client is a package that is ready to be published. After running `smithy build`, the generated client artifacts will be in the build directory under the projection and plugin name. For example, generated client artifacts for the source projection using the `typescript-client-codegen` plugin in a Smithy CLI project would be in the `build/smithy/source/typescript-client-codegen/` directory. A common practice is to copy the generated client artifacts into a source control repository. After the artifacts are staged, any modifications that are needed prior to publishing the generated client artifacts specific to the SDK should be run, e.g. adding a `README.md`, editing changelog entries. Finally, with a chosen publishing tool for the SDK, publish the artifacts after running the `prepack` script per client package.

### Server SDK code generation: `typescript-server-codegen` plugin

For documentation of `typescript-server-codegen` artifacts and implementation, see [the Smithy TypeScript Server SDK walkthrough](https://smithy.io/2.0/ts-ssdk/index.html) and [Developer Preview announcement blog post](https://aws.amazon.com/blogs/devops/smithy-server-and-client-generator-for-typescript).

#### `typescript-server-codegen` plugin configuration

> Note: Although plugin configuration is maintained with backward compatibility in mind, breaking changes may still occur.

[`TypeScriptSettings`](smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptSettings.java) contains all of the settings enabled from `smithy-build.json` and helper methods and types. The up-to-date list of top-level properties enabled for `typescript-server-codegen` can be found in `TypeScriptSettings.ArtifactType.SSDK`.

|Setting|Required|Description|
|---|---|---|
|`package`|Yes|Name of the package in `package.json`.|
|`packageVersion`|Yes|Version of the package in `package.json`.|
|`packageDescription`|No|Description of the package in `package.json`. The default value is `${package} server`.|
|`packageJson`|No|Custom `package.json`properties that will be merged with the base `package.json`. The default value is an empty object.|
|`packageManager`|No|Configured package manager for the package. The default value is `yarn`.|
|`service`|No|The Shape ID of the service to generate a client for. If not provided, the code generator will attempt to infer the service Shape ID. If there is exactly 1 service found in the model, then the service is used as the inferred Shape ID. If no services are found, then code generation fails. If more than 1 service is found, then code generation fails.|
|`protocol`|No|The Shape ID of the protocol used to generate serialization and deserialization. If not provided, the code generator will attempt to resolve the highest priority service protocol supported in code generation (registered through `TypeScriptIntegration`). If no protocols are found, code generation will use serialization and deserialization error stubs.|
|`private`|No|Whether the package is `private` in `package.json`. The default value is `false`.|
|`requiredMemberMode`|No|**NOT RECOMMENDED DUE TO BACKWARD COMPATIBILITY CONCERNS.** Sets whether members marked with the `@required` trait are allowed to be `undefined`. See more details on the risks in `TypeScriptSettings.RequiredMemberMode`. The default value is `nullable`.|
|`createDefaultReadme`|No|Whether to generate a default `README.md` for the package. The default value is `false`.|
|`disableDefaultValidation`|No|Whether or not default validation is disabled. See [the documentation for Smithy TypeScript SSDK validation](https://smithy.io/2.0/ts-ssdk/validation.html) to learn more. The default value is `false`.|

### Adding customizations to Smithy TypeScript

#### Using third-party packages
Expand Down Expand Up @@ -516,6 +491,8 @@ An example of a Java Gradle project that provides customizations can be found in

#### TypeScript client configuration

TODO: client option functions

During code generation, code generators should provide a default value for each client's input configuration property through a client's runtime configuration. If there are use cases in which configuration may need a specific set of values (e.g. specific features like using HTTP/2), writing a `RuntimeExtension` that has those specific configuration property values may make sense.

For example, a team that publishes a client for the `Weather` service in a package named `@example/weather` may write and publish a `RuntimeExtension` that provides the configuration values needed to use HTTP/2 with the service:
Expand Down

0 comments on commit d3864eb

Please sign in to comment.