Skip to content

Commit

Permalink
feat(docs): update docs
Browse files Browse the repository at this point in the history
Updates the Wing docs. See details in [workflow run].

[Workflow Run]: https://github.com/winglang/docsite/actions/runs/6331390161

------

*Automatically created via the "update-docs" workflow*

Signed-off-by: monabot <[email protected]>
  • Loading branch information
monadabot committed Sep 27, 2023
1 parent 1c7213f commit cca0f92
Show file tree
Hide file tree
Showing 4 changed files with 397 additions and 17 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ One that has finished, you can run `pnpm build` and the new bindings should be g

A resource in the SDK has several parts:

* A preflight [polycon](https://github.com/winglang/polycons) API that is shared across all cloud targets. Resource polycons are defined in `src/cloud`. For example, [`src/cloud/bucket.ts`](https://github.com/winglang/wing/tree/main/libs/wingsdk/src/cloud/bucket.ts).
* A set of base APIs that must be implemented by all cloud targets. Typically the resource's preflight APIs correspond to a base class in TypeScript, and the resource's inflight APIs correspond to an interface in TypeScript. These are defined in `src/cloud` or `src/ex`. For example, [`src/cloud/bucket.ts`](https://github.com/winglang/wing/tree/main/libs/wingsdk/src/cloud/bucket.ts).
* An interface representing the inflight API common across all cloud targets. By convention, if the resource is named like `Gizmo`, the inflight interface should be named `IGizmoClient`. This is usually in the same file as the preflight API.
* A simulator implementation in `src/sim`. This includes:
* A schema with information to simulate the resource and display the resource in the Wing console. Currently these are in [`src/sim/schema-resources.ts`](https://github.com/winglang/wing/tree/main/libs/wingsdk/src/sim/schema-resources.ts).
Expand Down Expand Up @@ -137,23 +137,12 @@ Constructs with the same parent are required to have different ids.
When a tree of constructs all implement a method like `toTerraform()`, then it is possible to traverse the construct tree and aggregate the result of calling the method on each construct in order to synthesize a result or artifact.

### Polycons
### Target-specific classes

In order to model resources that are implemented differently for each cloud provider, the SDK also uses [polycons](https://github.com/winglang/polycons), a [dependency injection](https://en.wikipedia.org/wiki/Dependency_injection) framework designed to work with constructs.
In order to model resources that are implemented differently for each compiler target, the SDK uses a form of [dependency injection](https://en.wikipedia.org/wiki/Dependency_injection).

Using polycons, the SDK resources are structured as follows:

* Each resource has a polycon class defined in the `cloud` namespace with the API that is shared across all cloud implementations (e.g. `cloud.Bucket`).
In order to work with polycons, any shared properties and methods expected to exist on all classes must be defined on a base clase like `cloud.BucketBase`, and then we have `cloud.Bucket` extending `cloud.BucketBase`.
Each polycon also has a unique polycon type name needed for polycons to perform dependency injection on them.
* Each cloud target can implement a polycon by defining a class that extends the polycon base class (e.g. `tfaws.Bucket` extends `cloud.BucketBase`).
* Each cloud target defines a [polycon factory](https://github.com/winglang/polycons/blob/main/API.md#ipolyconfactory-) that defines the concrete mapping from polycon type names to polycon implementations.
* Each cloud target has a unique `App` construct that specifies logic for synthesizing a one or more types of constructs.
It also registers the cloud target's polycon factory to that node on the construct tree.

Through polycons, when a user writes `new cloud.Bucket()` within the scope of an AWS `App`, the constructor of `cloud.Bucket` will automatically look up the polycon factory associated with the construct tree, and call the factory's `resolve` method to produce the class instance specific to that cloud target (`new tfaws.Bucket()`), and return that back to the caller.

Each `App` class has an automatically registered polycon factory, but it's possible to pass a custom factory in `new App(...)` that builds on top of (or overrides) the original factory to support more polycons, or different resolution behavior.
Each target has its own internal class named `App`, and the `App` class implements a method named `tryNew` that is responsible for taking the fully name of a class (like `@winglang/sdk.cloud.Bucket`) and instantiating the relevant class for that target (like `@winglang/sdk.tfaws.Bucket`).
See [src/target-tf-aws/app.ts](https://github.com/winglang/wing/blob/6d29256892c6362b823c9369f3ec0560ee69697a/libs/wingsdk/src/target-tf-aws/app.ts#L75-L81) for an example.

### Inflights

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ keywords: [rfcs, rfc, overview, process]
An RFC is short for "request for comments". It's a document that describes a new feature or change
to Wing. It's a way to propose, gather feedback, and reach consensus for a change from maintainers,
contributors, and users before writing any code. For an example of an RFC, check out:
https://www.winglang.io/contributing/rfcs/2022-06-14-polycons
https://www.winglang.io/contributing/rfcs/stdlib

Usually, an RFC is a common practice for major features or complex changes that require that extra
vetting. However, the process is designed to be as lightweight as needed and can be used to request
Expand Down
23 changes: 23 additions & 0 deletions versioned_docs/version-latest/03-language-reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -1771,6 +1771,29 @@ bring cloud; // from cloud bring * as cloud;
bring "cdktf" as cdktf; // from "cdktf" bring * as cdktf;
```
To import an individual Wing file as a module, you can specify its path relative
to the current file:
```TS
bring "./my-module.w" as myModule;
```
It's also possible to import a directory as a module. The module will contain all
public types defined in the directory's files. If the directory has subdirectories,
they will be available under the corresponding names.
```TS
bring "./my-module" as myModule;
// from ./my-module/submodule/my-class.w
new myModule.submodule.MyClass();
```
The following features are not yet implemented, but we are planning to add them in the future:
* Specify types as public using `pub` - see https://github.com/winglang/wing/issues/4294 to track.
* Specify types as public within the current project or library, and private outside, using `internal` - see https://github.com/winglang/wing/issues/4156 to track.
[`top`][top]
---
Expand Down
Loading

0 comments on commit cca0f92

Please sign in to comment.