After an amazing ride, we’ve made the tough decision to shut down our company, Wing (previously Monada).

We started this journey with a bold idea: what if building in the cloud didn’t have to be so hard? What if infrastructure and application code could live together—beautifully and seamlessly? So we created Winglang—a programming language designed to realize that vision.

We open-sourced it, and the response blew us away: over 100 contributors, lots of excitement, and an awesome community that formed around it.

But when we tried to turn that energy into a business, we hit some tough reality checks. While developer experience is something engineers care deeply about, it’s not always seen as business-critical by most companies. That made it hard to build a sustainable business around it.

Over the past year, we explored various different directions in the cloud space—looking for a problem we were both passionate about and could build a company around. In the end, we didn’t find the right fit.

So, we’re bringing this chapter to a close. It’s bittersweet, but we’re deeply proud of what we built—and even more grateful for the amazing people who joined us along the way. Winglang was a labor of love, and building it was an absolute blast.

Huge shoutout to all the incredible Wingians/Monadians who were part of this journey—and a massive thank you to our amazing investors for believing in us and backing this wild ride. Your trust and support meant the world. 🙏

And in case you missed it: the first (and quirkiest) episode of The Wingly Update will always be a reminder of how much fun this all was: https://lnkd.in/dByGyq9m

The 11th issue of the Wing Inflight Magazine.

Howdy Wingnuts!

We are back with another monthly issue of the Wing Inflight Magazine and excited to share some updates about Winglang, an open source-programming language for the cloud.

New to Wing? Let’s get you up to date. Wing is a new programming language designed to help developers and platform engineers build cloud first applications with the best developer experience. The language combines cloud infrastructure and runtime into a single programming model and compiles to Terraform/CloudFormation and JavaScript that are ready to deploy to AWS, GCP and Azure (see our support matrix).

We are designing Wing to be familiar and friendly for developers who come from modern object-oriented background, so it will take you 5 minutes to learn.

Check out our getting started tutorial or hit the Wing Playground for an online experience.

In today’s issue​

• New homepage for Wing
• Introducing Wing by example
• New Bytes type in Wing
• CORS Configuration for Cloud Buckets
• New Wing intrinsics for @app and @filename
• Generate API documentation using the Wing CLI
• Wing Console updates
  • Presigned URLS now supported in the console
• winglibs
  • New email winglib
  • DynamoDB billing mode and deletion protection now enabled
• Summary

New homepage for Wing​

We’re excited to unveil the updated Winglang.io landing page. It now features live Wing code examples, a streamlined search function to quickly find documentation, and easy access to the broader Wing ecosystem and programming language resources.

If you encounter any issues or have feedback, please share them with us via our docs site repository.

Introducing Wing by example​

Many programming languages, such as Go, Rust, Haskell, and Python, feature "by example" pages. These resources offer quick code snippets and examples to help developers grasp various language concepts efficiently.

Drawing inspiration from these, we’ve launched our own Wing by Example page. It provides a hands-on introduction to Wing through annotated example programs. You can explore over 30 examples on our website.

Feel free to contribute any missing examples or suggest improvements to our documentation through our docs site repository. Your feedback and contributions help us enhance the learning experience for the entire community.

New Bytes type in Wing​

When working with binary files like images, audio, or other binary formats, you often need to manipulate data at the byte level. Wing now introduces a new bytes type, allowing you to easily handle byte values from strings, hexadecimal values, and files.

// get bytes from raw value
let rawData: bytes = bytes.fromRaw([104, 101, 108, 108, 111]);

// get the bytes from a string
let rawString: bytes = bytes.fromString("hello");

// get bytes from base64 encoded value
let base64: bytes = bytes.fromBase64("aGVsbG8=");

// get bytes from hex value
let hex: bytes = bytes.fromHex("68656c6c6f");

You can also use the fs module to read and write bytes to disk, making it easier to manage binary data in your applications.

bring fs;

// get bytes from file
let rawData: bytes = fs.readBytes("path/to/file");

// write bytes to a file
fs.writeBytes("path/to/file", rawData);

The bytes type in Wing is immutable. While mutable bytes (mutbytes) are not currently supported, they are on our roadmap. If you'd like to see this feature added, please consider upvoting the issue to show your support.

To learn more, you can refer to the new bytes type in the Language Reference or try it out yourself with this playground example for a hands-on experience.

CORS Configuration for Cloud Buckets​

CORS (Cross-Origin Resource Sharing) support for cloud.Bucket has now been added with the default option set to true. cors and corsOptions have now been added as properties on the cloud.Bucket resource.

bring cloud;
bring http;

let uploads = new cloud.Bucket(
  // these are the default values, override them if you need too
  public: false,
  cors: true,
  corsOptions: {
    allowedMethods: [http.HttpMethod.GET, http.HttpMethod.POST, http.HttpMethod.PUT, http.HttpMethod.DELETE, http.HttpMethod.HEAD],
    allowedOrigins: ["*"],
    allowedHeaders: ["*"],
    exposeHeaders: [],
    maxAge: 0s
  },
);

You can disable the CORS configuration and apply custom rules to your buckets as needed.

bring cloud;
bring http;

let bucket = new cloud.Bucket(
  cors: false, // disable any default CORS rules
);

// example of custom CORS rule
bucket.addCorsRule({
  allowedOrigins: ["https://example.com"],
  allowedMethods: [http.HttpMethod.GET],
});

When CORS is enabled (cors: true), signed URLs will work automatically, allowing you to upload or download files directly from your browser to your bucket without additional configuration.

If your bucket is public or you're heavily using signed URLs, you may want to customize the corsOptions settings or disable CORS entirely based on the needs of your application.

For more details, you can read the documentation or try it out in our playground.

New Wing intrinsics for @app and @filename​

Intrinsic functions are a special call-like expressions built into the Wing compiler. Wing now supports two new instrinc functions called @filename and @app.

• @filename can be used to get the absolute path of the source file (example)
• @app represents a wing application (see documentation)

// bring http;
bring cloud;

// absolute path of the source file
let name = @filename;

// the root of the construct tree 
let app = @app;

// true if this is a testing environment.
let isTest = app.isTestEnvironment;

// The application's parameter registrar.
let params = app.parameters;

// The directory of the entrypoint of the current Wing application.
let entrypointDir = app.entrypointDir;

// The .wing directory into which you can emit intermediate artifacts during preflight.
let workdir = app.workdir;

Wing application developers and library authors can use intrinsic functions to help them. You can discover and read more intrinsic functions via our documentation.

Generate API documentation using the Wing CLI​

Wing now supports a new command called wing docs. Running this command will generate a API.md file in your current directory. These files can be shared with developers to help them understand your Wing code (see DynamoDB winglib example).

Here is an example using doc comments (///) in your Wing code. Running wing docs compiles this into a markdown file.

/// Winglib example that send messages to people
pub class Email {

    /// Name of the person to say hello too
    pub name: str;

    new(name: str){
        this.name = name;
    }
    /// Say Hello to everyone in the world
    pub sendMessage(message:str){
        log("Sending message to {this.name}: {message}");
        // ... logic to send message
    }
}

Generated markdown

## API Reference

### Table of Contents

- **Classes**
  - <a href="#my-wing-app.Email">Email</a>

### Email (preflight class) <a class="wing-docs-anchor" id="my-wing-app.Email"></a>

Winglib example that send messages to people

#### Constructor

``
new(name: str): Awesome
``

#### Properties

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| <code>name</code> | <code>str</code> | Name of the person to say hello too |

#### Methods

| **Signature** | **Description** |
| --- | --- |
| <code>sendMessage(message: str): void</code> | Say Hello to everyone in the world |

wing docs can be useful for developers building winglibs. Using this new command can help you document your libraries and examples for other wing developers.

If you want to learn more about winglibs or start creating your own you can read our getting started guide.

Wing console updates

The Wing Console is a web application that is designed to enhance the developer experience when viewing, exploring and interacting with your Wing applications. The wing console provides instant feedback during cloud application development process.

Presigned URLS now supported in the console​

Uploading and downloading files using presigned URLS with the cloud.Bucket resource is now also supported in the Wing console. When your application uploads files to the bucket you can now visually see the files, interact with them and delete them.

bring cloud;
bring http;

// Create a new bucket
let bucket = new cloud.Bucket(cors: true);

// create new function
new cloud.Function(inflight () => {

	// generate presigned url
  let url = bucket.signedUrl("my-key", {
    action: cloud.BucketSignedUrlAction.UPLOAD,
    duration: 2m
  });

  // Example uploading file using the url
  // This would be your web application...
  let response = http.put(url, {
    headers: {
        "Content-Type": "text/plain",
        "Content-Disposition": "attachment; filename=text.txt"
    },
    body: "Hello world"
  });


  // 200
  log(response.status);

}) as "Upload file using presigned url";

Wing console output. You can see and explore this example in our playground.

winglibs​

Wing libraries (winglibs) are packages you can import into your wing application. Anybody can create a winglib and add them to our ecosystem of libraries.

New wing packages​

Here is a list of new wing packages or improvements that have been made

• @winglibs/email - Send emails using Wing.
• @winglibs/dynamodb - Now supports BillingMode and deletion protection.

Have an idea for a new winglib? Feel free to reach out to us on Discord or make a pull request on GitHub.

Summary​

That’s it for this edition!

You are invited to join the Wing Discord! Come say hello and hang out with fellow Wingnuts! Give winglang.io a visit and take Wing out for a spin. If you're not already, stay updated on the latest changes in our repo.

Catch you next month!

- The Wing Team

We recently updated the project's roadmap to share more details about our vision for the project. As the Wing language and toolchain has an ambitious goal, we're hoping this gives you a better idea of what to expect in the coming months.

We want to stabilize as many of the items below as possible and we're eagerly interested in you feedback and collaboration, either through GitHub or our Discord server.

Toolchain​

Wing CLI​

• We want to provide a robust CLI for people to compile, test, and perform other essential functions with their Wing code.

• We want the CLI to be easy to install, update, and set up on a variety of systems.

• Dependency management should be simple and insulated from problems specific to individual Node package managers (e.g npm, pnpm, yarn).

• The Wing toolchain makes it easy to create and publish Wing libraries (winglibs) with automatically generated API docs, and it doesn't require existing knowledge of node package managers.

Wing Platforms​

• Wing Platforms allow you to specify a layer of infrastructure customizations that apply to all application code written in Wing. It should be simple to create new Wing platforms or extend existing platforms.

• With Wing Platforms it's possible to specify both multi-cloud abstractions in Wing as well as the actual platform (for example, the implementation of cloud.Bucket) in Wing.

Testing​

• Wing lets you easily write tests that run both locally and on the cloud.

• Wing test runner can be customized per platform.

• Tests in Wing can be run in a variety of means -- via the CLI, via the Wing Console, and in CI/CD.

• The design of the test system should make it easy for developers to write reproducible (or deterministic) tests, and also provide facilities for debugging.

Compiler​

• Wing's syntax and type system is robust, well documented, and easy for developers to learn.

• Developers coming from other mainstream languages with C-like syntax (Java, C++, TypeScript) should feel right at home.

• Most Wing code is statically typed in order to support automatic permissions.

• Wing should be able to interoperate with a vast majority of TypeScript libraries.

• It should be straightforward to import libraries that are available on npm and automatically have corresponding Wing types generated for them based on the TypeScript type information.

• The language also has mechanisms for more advanced users to use custom JavaScript code in Wing.

• We want Wing to have friendly, easy to understand error messages that point users towards how to fix their problems.

• Wing has a built-in language server that gives users a first-class editing and refactoring experience in their IDEs.

Standard Library and Ecosystem​

• Wing provides a batteries-included experience for performing common programming tasks like working with data structures, file systems, calculations, random number generation, HTTP requests, and other common needs.

• Wing also has a ecosystem of Wing libraries ("winglibs") that make it easy to write cloud applications by providing easy-to-use abstractions over popular cloud resources.

• This includes a []cloud module](/docs/api/category/cloud) that is an opinionated set of resources for writing applications on the most popular public clouds.

• The cloud primitives are designed to be cloud-agnostic (we aren't biased towards a specific cloud provider).

• These cloud primitives all can be run to a high degree of fidelity and performance with the local simulator.

• Not all winglibs may be fully stable when the language reaches 1.0.

Wing Console / Simulator​

• We want to provide a first class local development experience for Wing that makes it easy and fast to test your applications locally.

• It gives you observability into your running application and interact live with different components.

• It gives you a clearer picture of your infrastructure graph and how preflight and inflight code are related.

• It complements the experience of writing code in a dedicated editor.

Documentation​

• We want it to be easy for people to get exposed to Wing code and have ways to try applications without having to install Wing locally.

• The Wing docs should provide content appealing to different kinds of developers trying to acquire different kinds of information at different stages -- from tutorials to references to how-to-guides (documentation quadrants)

• Wing docs need to have content for both the personas of developers writing their own applications and platform engineers aiming to provide simpler abstractions and tools for their teams.

• We want to provide hundreds of examples and code snippets to make it easy to learn the syntax of the language and easy to see how to solve common use cases.

If you have any questions, would like to contribute feel free to reach out to us and join us on our mission to make cloud development easier for everyone.

- The Wing Team

The 10th issue of the Wing Inflight Magazine.

Howdy Wingnuts!

We are back with another monthly issue of the Wing Inflight Magazine and excited to share some updates about Winglang, an open source-programming language for the cloud.

New to Wing? Let’s get you up to date. Wing is a new programming language designed to help developers and platform engineers build cloud first applications with the best developer experience. The language combines cloud infrastructure and runtime into a single programming model and compiles to Terraform/CloudFormation and JavaScript that are ready to deploy to AWS, GCP and Azure (see our support matrix).

We are designing Wing to be familiar and friendly for developers who come from modern object-oriented background, so it will take you 5 minutes to learn.

Check out our getting started tutorial or hit the Wing Playground for an online experience.

In today’s issue​

• Wing 1.0 roadmap
• Language updates
  • Internal access modifier
  • New cloud resource cloud.Service
  • AWS Lambda Layer API for Wing
  • Logging now supports more values
  • Breaking changes
    • Goodbye elif, hello else if
    • inflight intrinsic has been removed
    • cloud.Function now accepts Json
    • Additional breaking changes
• Wing Console updates
  • New table component ui.Table
  • Nodes can be collapsed or expanded
  • Ability to filter logs in the Wing console
• WingLibs
  • New wing packages
• Summary

Wing 1.0 roadmap​

We're excited to share our 1.0 roadmap, outlining our vision and the goals we aim to achieve in Wing 1.0.

Our mission with Wing is to empower developers to build cloud applications with an exceptional developer experience. To do this, we're focusing on establishing a stable foundation for the Wing programming language, defining essential cloud primitives, enabling the creation of libraries (winglibs) and custom platforms, and providing tools to simulate the cloud locally on your machine.

Building on the cloud shouldn’t be difficult, and we believe Wing can be a key part of the solution.

As we progress toward Wing 1.0, we'll be experimenting, learning, and making necessary adjustments. If you'd like to contribute or join us on this journey, we'd love to connect with you on GitHub or through our Discord server.

Language updates​

To get the latest language updates you will need to update your wing version running the command below

npm install -g winglang

Internal access modifier​

Wing now supports the internal access modifier, which is particularly useful for library authors (winglib authors). This modifier allows you to make classes or methods accessible only within the module or library you’re developing, keeping them hidden from external consumers.

Previously, the only option if you were splitting definitions across multiple files was to make everything public, exposing all methods and classes to the library users. With internal, you gain finer control over what parts of your code are exposed, ensuring that only what’s necessary is accessible.

This example shows a internal class called OrderProcessingUtils. As a library author you can call OrderProcessingUtils.calculateTax within the module itself, but library consumers cannot (as it’s not exposed).

internal class OrderProcessingUtils {
    static calculateTax(amount: num): num {
        // Internal method to calculate tax
        return amount * 0.1;
    }
}

// OK inside the module we are building
let value = OrderProcessingUtils.calculateTax(10);

// Will not work if we try to use the code outside the module
let value = OrderProcessingUtils.calculateTax(10); // error

You can read more on our documentation about access modifiers.

New cloud resource cloud.Service​

We have released the new cloud.Service resource. The cloud.Service class in Wing represents a cloud service with a defined lifecycle, including a start and an optional stop phase.

Example usage includes long-running processes like microservices or background data processing.

Cloud services will automatically start once deployed, you can opt out of this by specifying the autoStart option.

bring cloud;

// inflight (runtime code) that is run within the service
let handler = inflight () => {
	// Code is run on init/start of service
	// This example we can start a custom HTTP server
  log("Service started...");
  let server = startHttpServer();
  
  // Code is run when service stops
  return () => {
    log("Service stopped...");
    // Example would be to stop the HTTP server
    server.close();
  };
};

// By default services are started when deployed
let autoStartService = new cloud.Service(handler);

// You can configure services not to start on deploy
let manualStartService = new cloud.Service(handler, autoStart: false);

Cloud services also have an inflight API that allows you to start or stop the service yourself, if you want more fine-grained control.

bring cloud;

let startCounter = new cloud.Counter() as "start counter";
let stopCounter = new cloud.Counter() as "stop counter";

let handler = inflight() => {
  let i = startCounter.inc();
  log("Service started for the ${i}th time...");
  return () => {
    let i = stopCounter.inc();
    log("Service stopped for the ${i}th time...");
  };
};

let service = new cloud.Service(handler, autoStart: false);

// Access service inflight API to start/stop the service in functions
new cloud.Function(inflight() => {
  service.start();
  assert(service.started());
}) as "start service";

new cloud.Function(inflight() => {
  service.stop();
  assert(!service.started());
}) as "stop service";

cloud.Service currently supports the AWS platform (terraform and CDK), if you would like Azure or Google Cloud (GCP) support please comment and upvote the GitHub issues.

You can get started or read more in the documentation.

AWS Lambda Layer API for Wing​

When compiling cloud.Function resources to the AWS platform, AWS Lambda is used.

AWS Lambda supports lambda layers, which contain supplementary code or data for your Lambda functions. These can be useful for sharing library dependencies, a custom runtime or configuration files across your Lambda functions.

Wing now supports adding Lambda layers to cloud.Function. To add a Lambda layer to your function, you can now use the aws.Function class as shown below.

bring aws;
bring cloud;

// define your cloud function
let f = new cloud.Function(inflight () => {
  log("Hello world!");
});

// attach lambda layer to the function
if let lambdaFn = aws.Function.from(f) {
	// add your lambda layer
  lambdaFn.addLambdaLayer("arn:aws:lambda:us-west-2:123456789012:layer:my-layer:1");
}

You can also attach Lambda layers to all your cloud functions by using a classe’s inflight method and the onLift hook. This allows you abstract and apply layers at a global level, ideal if you want to create winglibs for your developers.

bring aws;
bring cloud;

// Create Datadog class for wing application
class Datadog {
  pub inflight fetchMetrics() {
    // ...implementation...
  }
  // onLift hook, attach the lambda layer
  pub onLift(host: std.IInflightHost, ops: Array<str>) {
    if let lambdaFn = aws.Function.from(host) {
      lambdaFn.addLambdaLayer("arn:aws:lambda:us-west-2:123456789012:layer:datadog-layer:1");
    }
  }
}

let d = new Datadog();

let api = new cloud.Api();

// Lambda layer is attached to inflight function
api.get("/metrics", inflight () => {
  d.fetchMetrics();
});

If you want to learn more you can read the documentation.

Logging now supports more values​

Logging now supports stringable values directly rather than wrapping them with quotes.

enum MyEnum { A, B, C }
let x = 5;

// before
log("{x}");
log("my string");
log("{42}");
log("{true}");
log("{Json { "cool": "beans" }}");
log("{MyEnum.A}");

// now
log(x);
log("my string");
log(42);
log(true);
log(Json { "cool": "beans" });
log(MyEnum.A);

Breaking changes​

As we move towards Wing 1.0, we will be making changes along the way. Some of these changes may break existing code, but we will do our best to document these and keep you updated.

Goodbye elif, hello else if​

To align with other imperative languages and improve the ease of picking up Wing we have removed elif and replaced it with else if .

We recommend running a simple find and replacement over your codebase (like find . -type f -name "*.w" -exec perl -pi -e 's/\belif\b/else if/g' {} +) to update to the new syntax.

let x: num = 11;

// before
if x <= 10 {
  log("{x} is less than or equal to 10");
} elif x > 10 {
  log("{x} is greater than 10");
}

// after
if x <= 10 {
  log("{x} is less than or equal to 10");
} else if x > 10 {
  log("{x} is greater than 10");
}

Read more in the pull request (https://github.com/winglang/wing/pull/6976)

ex.Table and ex.Redis are now winglibs​

ex.Redis and ex.Table have not been removed from the standard library in favour of dedicated libraries. You can now use the winglibs for Redis, DynamoDB and Postgres.

@inflight intrinsic has been removed​

Wing supports interoperating with TypeScript and JavaScript code, these methods were previously using externs or @inflight. The interoperating with TypeScript allows you to use TypeScript code within your Wing applications.

After using @inflight and through user feedback we found a few DX issues with the intrinsic (read pull request for more information). For this reason we decided to remove the intrinsic and recommend developers to use the extern method .

cloud.Function now accepts Json​

The input and return types for cloud.Function has been changed from optional string (str?) to optional JSON (Json?) to align with event formats used by major cloud providers like AWS, GCP and Azure.

bring cloud;

// before
let x = new cloud.Function(inflight (payload: str?) => {
  let data = Json.stringify(payload);
  log(data);
});

// after 
let x = new cloud.Function(inflight (payload: Json?) => {
  log(Json.stringify(payload));
});

Additional breaking changes​

• winglib cdk8s has been renamed to k8s (https://github.com/winglang/winglibs/pull/298)
• .node has been removed in favor of nodeof() - https://github.com/winglang/wing/pull/6721
• Removed “Optional test” operator - https://github.com/winglang/wing/pull/6804
• change cloud.Function event type from str to Json - https://github.com/winglang/wing/pull/6219

Wing console updates​

The Wing Console is a web application that is designed to enhance the developer experience when viewing, exploring and interacting with your Wing applications. The wing console provides instant feedback during cloud application development process.

New table component ui.Table​

Wing allows developers to create their own resources. These resources are shown in the Wing console. Using the ui standard library it’s possible to add custom components for interacting with your resources and displaying information, like Buttons, Fields, FileBrowsers and now Tables.

In this example we create a new Stripe resource with a few public methods. When developers interact with this resource using the Wing console they can also see a list of customers in a table (using the ui.Table resource and populating it with custom data).

Tables can be used to show any information represented by JSON into the wing console.

To learn more and get started you can read the documentation.

Nodes can now be collapsed and expanded​

Nodes in the Wing console can now be expanded or collapsed, helping you navigate the map view in the Wing console.

You can try it out yourself in our playground.

Ability to filter logs in the Wing console​

New filter capabilities have now been added to the console. This gives developers the ability to quickly filter logs within the Wing Console.

Winglibs​

Wing libraries (winglibs) are packages you can import into your wing application. Anybody can create a winglib and add them to our eco system of libraries.

New wing packages​

Here is a list of new wing packages that have been released

• @winglibs/momento - Use the Momento cache with Wing.
• @winglibs/slack - Integrate with Slack using Wing.
• @winglibs/ses - Interact with the AWS SES ervice
• @winglibs/sns - Interact with the AWS SNS service

Have an idea for a new winglib? Feel free to reach out to us on Discord or make a pull request on GitHub.

Summary​

That’s it for this edition!

You are invited to join the Wing Discord! Come say hello and hang out with fellow Wingnuts! Give winglang.io a visit and take Wing out for a spin. If you're not already, stay updated on the latest changes in our repo.

Catch you next month!

- The Wing Team

Blue Zone Application from “Hexagonal Architecture Explained​

Fig 1: The “Blue Zone” Application Ported to Cloud with Wing

Directly porting software applications to the cloud often results in inefficient and hard-to-maintain code. However, using the new cloud-oriented programming language Wing in combination with Hexagonal Architecture has proven to be a winning combination. This approach strikes the right balance between cost, performance, flexibility, and security.

In this series, I will share my experiences migrating various applications from mainstream programming languages to Winglang. My first experience implementing the Hexagonal Architecture in Wing was reported in the article "Hello, Winglang Hexagon!”. While it was enough to acquire confidence in this combination, it was built on an oversimplified "Hello, World" greeting service, and as such lacked some essential ingredients and was insufficient to prove the ability of such an approach to work at scale.

In Part One, I focus on porting the “Blue Zone” application, featured in the recently published book “Hexagonal Architecture Explained”, from Java to Wing. The “Blue Zone” application brings in a substantial code base, still not too huge to dive into unmanageable complexity, yet representative of a large class of applications. Also, the fact that it was originally written in mainstream Java brings an interesting case study of creating a cloud-native variant of such applications.

This report also serves as a tribute to Juan Manuel Garrido de Paz, the book's co-author, who sadly passed away in April 2024.

Before we proceed, let's recap the fundamentals of the Hexagonal Architecture pattern.

The Hexagonal Architecture Pattern Essentials

Refer to Chapter Two of the “Hexagonal Architecture Explained” book for a detailed and formal pattern description. Here, I will bring an abridged recap of the main sense of the pattern in my own words.

The Hexagonal Architecture pattern suggests a simple yet practical approach to separate concerns in software. Why is the separation of concerns important? Because the software code base quickly grows even for a modest in terms of delivered value application. There are too many things to take care of. Preserving cognitive control requires a high-level organization in groups or categories. To confront this challenge the Hexagonal Architecture pattern suggests splitting all elements involved in a particular software application into five distinct categories and dealing with each one separately:

1. The Application itself. This category encapsulates the real value delivered to prospective customers and users. This is the reason why software is going to be developed and used in the first place. Sometimes, it’s called the Core or System Under Development (SuD). Another possible name for this part could be Computation - where external inputs are processed and final results are produced. Visually, the Application part of the system is represented in the form of a hexagon. There is nothing special or magic in this shape. As the “Hexagonal Architecture Explained” book authors explain:

“Hexagonal Architecture” has served well as a hook to the pattern. It’s easy to remember and generates conversation. However, in this book we want to be correct: The name of the pattern is “Ports & Adapters”, because there really are ports, and there really are adapters, and your architecture will show them.

2. External Actors that communicate with or are communicated by the Application. These could be human end users, electronic devices, or other Applications. The original pattern suggests further separation into Primary (or Driving) Actors - those who initiate an interaction with the Application, and Secondary (or Driven) Actors - those with whom the Application initiates communication.

3. Ports - a fancy name for formal specification of Interfaces the Primary Actors could use (aka Driving Ports) or Secondary Actors need to implement (aka Driven Ports) to communicate with the Application. In addition to the formal specification of the interface verbs (e.g. BuyParkingTicket) Ports also provide detailed specifications of data structures that are exchanged through these interfaces.

4. Adapters fill the gaps between External Actors and Ports. As the name suggests, Adapters are not supposed to perform any meaningful computations, but rather basically convert data from/to formats the Actors understand to/from data ****the Application understands.

5. Configurator pulls everything together by connecting External Actors to the Application through Ports using corresponding Adapters. Depending on the architectural decisions made and price/performance/flexibility requirements these decisions were trying to address, a specific Configuration can be produced statically before the Application deployment or dynamically during the Application run.

Contrary to popular belief, the pattern does not imply that one category, e.g. Application, is more important than others, nor does it suggest ultimately that one should be larger while others smaller. Without Ports and Adapters, no Application could be practically used. Relative sizes are often determined by non-functional requirements such as scalability, performance, cost, availability, and security.

The pattern suggests reducing complexity and risk by focusing on one problem at a time, temporally ignoring other aspects. It also suggests a practical way to ensure the existence of multiple configurations of the same computation each one addressing some specific needs be it test automation or operation in different environments.

The picture below from “Hexagonal Architecture Explained” book nicely summarizes all main elements of the pattern:

Fig 2: The Hexagonal Architecture Patterns in a Nutshell

“Blue Zone” Sample Application

From the application README:

BlueZone allows car drivers to pay remotely for parking cars at regulated zones in a city, instead of paying with coins using parking meters.

1. Driving actors using the application are car drivers and *parking inspectors.

2. Car drivers will access the application using a Web UI (User Interface), and they can do the following:

• Ask for the available rates in the city, in order to choose the one of the zone they want to park the car at.
• Buy a ticket for parking the car during a period of time at a regulated zone. This period starts at current date-time. The ending date-time is calculated from the paid amount, according to the rate (euros/hour) of the zone.

3. Parking inspectors will access the application using a terminal with a CLI (Command Line Interface), and they can do the following:

• Check a car for issuing a fine, in case that the car is illegally parked at a zone. This will happen if there is no active ticket for the car and the rate of the zone. A ticket is active if current date-time is between the starting and ending date-time of the ticket period.

4. Driven actors needed by the application are:

• Repository with the data (rates and tickets) used in the application. It also has a sequence for getting ticket codes as they are needed.
• Payment service that allows the car driver to buy tickets using a card. Obviously, no adapter for a real service has been developed, just a test-double (mock).
• Date-time service for obtaining the current date-time when needed, for buying a ticket and for checking a car.

I chose this application for two primary reasons. First, it was recommended by the “Hexagonal Architecture Explained” book as a canonical example. Second, it was originally developed in Java. I was curious to see what is involved in porting a non-trivial Java application to the cloud using the Wing programming language.

Where Do You Start From?

The “Hexagonal Architecture Explained” book provides reasonable recommendations in Chapter 4.9, “What is development sequence?”. It makes sense to start with “Test-to-Test” and proceed further. However, I did what most software engineers normally do— starting with translating the Java code to Wing. Within a couple of part-time days, I reached a stage where I had something working locally in Wing with all external interfaces simulated.

While technically it worked, the resulting code was far too big relative to the size of the application, hard to understand even for me, aesthetically unappealing, and completely non-Wingish. Then, I embarked on a two-week refactoring cycle, looking for the most idiomatic expression of the core pattern ideas adapted to the Wing language and cloud environment specifics.

What comes next is different from how I worked. It was a long series of chaotic back-and-forth movements with large portions of code produced, evaluated, and scrapped. This usually happens in software development when dealing with unfamiliar technology and domains.

Finally, I’ve come up with something that hopefully could be gradually codified into a more structured and systematic process so that it will be less painful and more productive the next time. Therefore, I will present my findings in the conceptually desirable sequence to be used next time, rather than how it happened in reality.

Thou Shalt Start with Tests

To be more accurate, the best and most cost-effective way is to start with a series of acceptance tests for the system's architecturally essential use cases. Chapter 5.1 of the “Hexagonal Architecture Explained” book, titled “How does this relate to use cases?”, elaborates on the deep connection between use case modeling and Hexagonal Architecture. It’s worth reading carefully.

Even the previous statement wasn’t 100% accurate. We are supposed to start with identifying Primary External Actors and their most characteristic ways of interacting with the system. In the case of the “Blue Zone” application, there are two Primary External Actors:

1. Card Driver
2. Parking Inspector

For the Car Drive actor, her primary use case would be “Buy Ticket”; for the Parking Inspector, his primary use case would be “Check Car”. By elaborating on these use cases’ implementation we will identify Secondary External Actors and the rest of the elements.

The preliminary use case model resulting from this analysis is presented below:

Fig 3: “Blues Zone” Application Use Case Mode

Notice that the diagram above contains only one Secondary Actor - the Payment Service and does not include any internal Secondary Actors such as a database. While these technology elements will eventually be isolated from the Application by corresponding Driven Ports they do not represent any Use Case External Actor, at least in traditional interpretation of Use Case Actors.

Specifying use case acceptance criteria before starting the development is a very effective technique to ensure system stability while performing internal restructurings. In the case of the “Blue Zone” application, the use case acceptance tests were specified in Gherkin language using the Cucumber for Java framework.

Currently, a Cucumber framework for Wing does not exist for an obvious reason - it’s a very young language. While an official Cucumber for JavaScript does exist, and there is a TypeScript Cucumber Tutorial I decided to postpone the investigation of this technology and try to reproduce a couple of tests directly in Wing.

Surprisingly, it was possible and worked fairly well, at least for my purposes. Here is an example of the Buy Ticket use case happy path acceptance test specified completely in Wing:

bring "../src" as src;
bring "./steps" as steps;

/*
Use Case: Buy Ticket
  AS
  a car driver
  I WANT TO
  a) obtain a list of available rates
  b) submit a "buy a ticket" request with the selected rate
  SO THAT
  I can park the car without being fined
*/
let _configurator = new src.Configurator("BuyTicketFeatureTest");
let _testFixture = _configurator.getForAdministering();
let _systemUnderTest = _configurator.getForParkingCars();
let _ = new steps.BuyTicketTestSteps(_testFixture, _systemUnderTest);

test "Buy ticket for 2 hours; no error" {
    /* Given */
        ["name",    "eurosPerHour"],
        ["Blue",    "0.80"],
        ["Green",   "0.85"],
        ["Orange",  "0.75"]
    ]);
    _.next_ticket_code_is("1234567890");
    _.current_datetime_is("2024/01/02 17:00");
    _.no_error_occurs_while_paying();
    /* When */
    _.I_do_a_get_available_rates_request();
    /* Then */
    _.I_should_obtain_these_rates([
        ["name",    "eurosPerHour"],
        ["Blue",    "0.80"],
        ["Green",   "0.85"],
        ["Orange",  "0.75"]
    ]);
    /* When */
    _.I_submit_this_buy_ticket_request([
        ["carPlate", "rateName", "euros", "card"],
        ["6989GPJ",  "Green",    "1.70",  "1234567890123456-123-062027"]
    ]);
    /* Then */
    _.this_pay_request_should_have_been_done([
        ["euros", "card"],
        ["1.70",  "1234567890123456-123-062027"]
    ]);
    /* And */
    _.this_ticket_should_be_returned([
        ["ticketCode", "carPlate", "rateName", "startingDateTime", "endingDateTime",   "price"],
        ["1234567890", "6989GPJ",  "Green",    "2024/01/02 17:00", "2024/01/02 19:00", "1.70"]
    ]);
    /* And */
    _.the_buy_ticket_response_should_be_the_ticket_stored_with_code("1234567890");
}

While it’s not a truly human-readable text, it’s close enough and not hard to understand. There are quite a few things to unpack here. Let’s proceed with them one by one.

The Test Structure​

The test above assumes a particular project folder structure and reflects the Wing module and import conventions, which states

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.

From the first two lines, we can conclude that the project has two main folders: src where all source code is located, and test where all tests are located. Further, there is a test\steps subfolder where individual test step implementations are kept.

The next three lines allocate a preflight Configurator object and extract from it two pointers:

1. _testFixture pointing to a preflight class responsible for the test setup
2. _systemUnderTest which points to a Primary Port Interface intended for Car Drivers.

Within the “Buy ticket for 2 hours; no errors”, we allocate an inflight BuyTicketTestSteps object responsible for implementing individual steps. Conventionally, this object gets an almost invisible name underscore, which improves the overall test readability. This is a common technique for developing a Domain-Specific Language (DSL) embedded in a general-purpose host language.

It’s important to stress, that while it did not happen in my case, it’s fully conceivable to start the project with a simple src and test\steps folder structure and a simple test setup to drive other architectural decisions.

Of course, with no steps implemented, the test will not even pass compilation. To make progress, we need to look inside the BuyTicketTestSteps class.

Test Steps Class​

The test steps class for the Buy Ticket Use Case is presented below:

bring expect;
bring "./Parser.w" as parse;
bring "./TestStepsBase.w" as base;
bring "../../src/application/ports" as ports;

pub class BuyTicketTestSteps extends base.TestStepsBase {
    _systemUnderTest: ports.ForParkingCars;
    inflight var _currentAvailableRates: Set<ports.Rate>;
    inflight var _currentBoughtTicket: ports.Ticket?;

    new(
        testFixture: ports.ForAdministering, 
        systemUnderTest: ports.ForParkingCars
    ) {
        super(testFixture);
        this._systemUnderTest = systemUnderTest;
    }
    
    inflight new() {
        this._currentBoughtTicket = nil;
        this._currentAvailableRates = Set<ports.Rate>[];
    }

    pub inflight the_existing_rates_in_the_repository_are(
        sRates: Array<Array<str>>
    ): void {
        this.testFixture.initializeRates(parse.Rates(sRates).toArray());
    }

    pub inflight next_ticket_code_is(ticketCode: str): void {
        this.testFixture.changeNextTicketCode(ticketCode);
    }

    pub inflight no_error_occurs_while_paying(): void {
        this.testFixture.setPaymentError(ports.PaymentError.NONE);
    }

    pub inflight I_do_a_get_available_rates_request(): void {
        this._currentAvailableRates = this._systemUnderTest.getAvailableRates();
    }

    pub inflight I_should_obtain_these_rates(sRates: Array<Array<str>>): void {
        let expected = parse.Rates(sRates);
        expect.equal(this._currentAvailableRates, expected);
    }

    pub inflight I_submit_this_buy_ticket_request(sRequest: Array<Array<str>>): void {
        let request = parse.BuyRequest(sRequest);
        this.setCurrentThrownException(nil);
        this._currentBoughtTicket = nil;
        try {
            this._currentBoughtTicket = this._systemUnderTest.buyTicket(request);
        } catch err {
            this.setCurrentThrownException(err);
        }
    }

    pub inflight this_ticket_should_be_returned(sTicket: Array<Array<str>>): void {
        let sTicketFull = Array<Array<str>>[
            sTicket.at(0).concat(["paymentId"]),
            sTicket.at(1).concat([this.testFixture.getLastPayResponse()])
        ];
        let expected = parse.Ticket(sTicketFull);
        expect.equal(this._currentBoughtTicket, expected);
    }

    pub inflight this_pay_request_should_have_been_done(sRequest: Array<Array<str>>): void {
        let expected = parse.PayRequest(sRequest);
        let actual = this.testFixture.getLastPayRequest();
        expect.equal(actual, expected);
    }

    pub inflight the_buy_ticket_response_should_be_the_ticket_stored_with_code(code: str): void {
        let actual = this.testFixture.getStoredTicket(code);
        expect.equal(actual, this._currentBoughtTicket);
    }

    pub inflight an_error_occurs_while_paying(error: str): void {
        this.testFixture.setPaymentError(parse.PaymentError(error));
    }

    pub inflight a_PayErrorException_with_the_error_code_that_occurred_should_have_been_thrown(code: str): void {
        //TODO: make it more specific
        let err = this.getCurrentThrownException()!;
        log(err);
        expect.ok(err.contains(code));
    }

    pub inflight no_ticket_with_code_should_have_been_stored(code: str): void {
        try {
            this.testFixture.getStoredTicket(code);
            expect.ok(false, "Should never get there");
        } catch err {
            expect.ok(err.contains("KeyError"));
        }
    }
}

This class is straightforward: it parses the input data, uniformly presented as Array<Array<str>>, into application-specific data structures, sends them to either testFixture or _systemUnderTest objects, keeps intermediate results, and compares expected vs actual results where appropriate.

The only specifics to pay attention to are the proper handling of preflight and inflight definitions. I’m grateful to Cristian Pallares, who helped me to make it right.

We have three additional elements with clearly delineated responsibilities:

1. Parser - ****Responsible for converting a uniform array of string inputs to the application-specific data structures.
2. Test Fixture - ****Responsible for backdoor communication with the system for preconditions setting and postconditions verification.
3. System Under Test - ****Responsible for implementing the application logic.

Let’s take a closer look at each one.

Parser​

The source code of the Parser module is presented below:

bring structx;
bring datetimex;
bring "../../src/application/ports" as ports;

pub class Util {
    pub inflight static Rates(sRates: Array<Array<str>>): Set<ports.Rate> {
        return unsafeCast(
            structx.fromFieldArray(
                sRates, 
                ports.Rate.schema()
            )
        );
    }

    pub inflight static BuyRequest(
	    sRequest: Array<Array<str>>
	  ): ports.BuyTicketRequest {
        let requestSet: Set<ports.BuyTicketRequest> = unsafeCast(
            structx.fromFieldArray(
                sRequest, 
                ports.BuyTicketRequest.schema()
            )
        );
        return requestSet.toArray().at(0);
    }

    pub inflight static Tickets(
	    sTickets: Array<Array<str>>
	  ): Set<ports.Ticket> {
        return unsafeCast(
            structx.fromFieldArray(
                sTickets, 
                ports.Ticket.schema(), 
                datetimex.DatetimeFormat.YYYYMMDD_HHMM
            )
        );
    }

    pub inflight static Ticket(sTicket: Array<Array<str>>): ports.Ticket {
        return Util.Tickets(sTicket).toArray().at(0);
    }

    pub inflight static PayRequest(
	    sRequest: Array<Array<str>>
	  ): ports.PayRequest {
        let requestSet: Set<ports.PayRequest> = unsafeCast(
            structx.fromFieldArray(
                sRequest, 
                ports.PayRequest.schema()
            )
        );
        return requestSet.toArray().at(0);
    }

    pub inflight static CheckCarRequest(
	    sRequest: Array<Array<str>>
	  ): ports.CheckCarRequest {
        let requestSet: Set<ports.CheckCarRequest> = unsafeCast(
            structx.fromFieldArray(
                sRequest, 
                ports.CheckCarRequest.schema()
            )
        );
        return requestSet.toArray().at(0);
    }
    
    pub inflight static CheckCarResult(
	    sResult: Array<Array<str>>
	  ): ports.CheckCarResult {
        let resultSet: Set<ports.CheckCarResult> = unsafeCast(
            structx.fromFieldArray(
                sResult, ports.CheckCarResult.schema()
            )
        );
        return resultSet.toArray().at(0);
    }

    pub inflight static DateTime(dateTime: str): std.Datetime {
        return datetimex.parse(
            dateTime, 
            datetimex.DatetimeFormat.YYYYMMDD_HHMM
        );
    }

    pub inflight static PaymentError(error: str): ports.PaymentError {
        return Map<ports.PaymentError>{
            "NONE" => ports.PaymentError.NONE,
            "GENERIC_ERROR" => ports.PaymentError.GENERIC_ERROR,
            "CARD_DECLINED" => ports.PaymentError.CARD_DECLINED
        }.get(error);
    }
}

This class, while not sophisticated from the algorithmic point of view, reflects some important architectural decisions with far-reaching consequences.

First, it announces a dependency on the system Ports located in the src\application\ports folder. Chapter 4.8 of the “Hexagonal Architecture Explained” book, titled “Where do I put my files?”, makes a clear statement:

The folder structure is not covered by the pattern, nor is it the same in all languages. Some languages (Java), require interface definitions. Some (Python, Ruby) don't. And some, such as Smalltalk, don't even have the concept of files!

It warns, however, that “we’ve observed that folder structures that don't match the intentions of the pattern end up causing damage”. For strongly typed languages like Java, it recommends keeping specifications of Driving and Driven Ports in separate folders.

I started with such a structure, but very soon realized that it just enlarges the size of the code and prevents it from taking full advantage of the Wing module and import conventions. Based on this I decided to keep all Ports in one dedicated folder. Considering the current size of the application, this decision looks justified.

Second, it exploits an undocumented Wing module and import feature that makes all public static inflight methods of a class named Util directly accessible by the client modules, which improves the code readability.

Third, it uses two Wing Standard Library extensions, datetimex, and structx developed to compensate for some features I needed. These extensions were part of my “In Search for Winglang Middleware” project endor.w, I reported about here, here, and here.

Justification for these extensions will be clarified when we look at the core architectural decision about representing the Port Interfaces and Data.

Representing Port Interfaces and Data​

Traditional strongly typed Object-Oriented languages like Java advocate encapsulating all domain elements as objects. If I followed this advice, the Ticket object would look something like this:

pub inflight class Ticket {
  pub ticketCode: str;
  pub carPlate: str;
  pub rateName: str;
  pub startingDateTime: std.Datetime;
  pub endingDateTime: std.Datetime;
  pub price: num;
  pub paymentId: str;
  
  new (ticketCode: str, ...) {
    this.ticketCode = ticketCode;
    ...
  }
  pub toJson(): Json {
    return Json {
       ticketCode = this.ticketCode,
       ...
  }
  pub static fromJson(data: Json): Ticket {
    return new Ticket(
      data.get("ticketCode").asStr(),
      ...
   );
  }
  pub toFieldArray(): Array<str> {
    return [
      this.ticketCode,
      ...
    ];
  }
  pub static fromFieldArray(records: Array<Array<str>>): Set<Ticket> {
    let result = new MutSet<Ticket>[];
    for record in records {
      result.add(new Ticket(
        record.at(0),
        ...
      );
    }
    return result.copy();
 }
} such

Such an approach introduces 6 extra lines of code per data field for initialization and conversation plus some fixed overhead of method definition. This creates a significant boilerplate overhead.

Mainstream languages like Java and Python try alleviating this pain with various meta-programming automation tools, such as decorators, abstract base classes, or meta-classes.

In Wing, all this proved to be sub-optimal and unnecessary, provided minor adjustments were made to the Wing Standard Library.

Here is how the Ticket data structure can be defined:

pub struct Ticket {                 //Data structure representing objects 
																		//with the data of a parking ticket:
    ticketCode: str;                //Unique identifier of the ticket;
                                    //It is a 10-digit number with leading zeros
                                    //if necessary
    carPlate: str;                  //Plate of the car that has been parked
    rateName: str;                  //Rate name of the zone where 
																    //the car is parked at
    startingDateTime: std.Datetime; //When the parking period begins
    endingDateTime: std.Datetime;   //When the parking period expires
    price: num;                     //Amount of euros paid for the ticket
    paymentId: str;                 //Unique identifier of the payment 
																    //made to get the ticket.
}

In Wing, structures are immutable by default, and that eliminates a lot of access control problems.

Without any change, the Wing Standard Library will support out-of-the-box Json.stringify(ticket) serialization to Json string and Ticket.fromJson(data) de-serialization. That’s not enough for the following reasons:

1. For data storage, we need conversion of the Ticket objects to Json rather than a Json string
2. Json serialization and de-serialization functions need to handle the std.Datetime fields correctly. Currently the Json.stringify() will convert any std.Datetime to an ISO string, but Ticket.fromJson() will fail.
3. To support test automation and different CSV formats, we need the ability to convert data structures to and from an array of strings.
4. There is a need for a more flexible conversion of strings to std.Datetime. For example, the “Blue Zone” application uses the YYYYMM HH:MM format.

All these additional needs were addressed in two Trusted Wing Libraries: datetimex and struct. While the implementation was not trivial and required a good understanding of how Wing and TypeScript interoperability works, it was doable with reasonable effort. Hopefully, these extensions can be included in future versions of the Wing Standard Library.

The special, unsafeCast function helped to overcome the Wing strong type checking limitations. To provide better support for actual vs expected comparison in tests, I decided that fromFieldArray(...) will return Set<...> objects. Occasionally it required toArray() conversion, but I found this affordable.

Now, let’s take a look at the main _systemUnderTest object.

ForParkingCars Port​

Following the “Hexagonal Architecture Explained” book recommendations, port naming adopts the ForActorName convention. Here is how it is defined for the ParkingCar External Actor:

pub struct BuyTicketRequest { 	//Input data needed for buying a ticket 
																//to park a car:
		carPlate: str;		//Plate of the car that has been parked
    rateName: str;		//Rate name of the zone where the car is parked at
    euros: num;				//Euros amount to be paid
    card: str;				//Card used for paying, in the format 'n-c-mmyyyy', where
	              			//	'n' is the card number (16 digits)
	              			//	'c' is the verification code (3 digits),
	              			//	'mmyyyy' is the expiration month and year (6 digits)
}

/**
 * DRIVING PORT (Provided Interface)
 */
pub inflight interface ForParkingCars {
	/**
	 * @return	A set with the existing rates for parking a car in regulated 
	 * zones of the city.
	 * If no rates exist, an empty set is returned.
	 */
     getAvailableRates(): Set<rate.Rate>;

    /**
	 * Pay for a ticket to park a car at a zone regulated by a rate,
	 * and save the ticket in the repository.
	 * The validity period of the ticket begins at the current date-time,
	 * and its duration is calculated in minutes by applying the rate,
	 * based on the amount of euros paid.
	 * @param request	Input data needed for buying a ticket.
	 * 					@see BuyTicketRequest
	 * @return	A ticket valid for parking the car at a zone regulated by the rate,
	 * 			paying the euros amount using the card.
	 * 			The ticket holds a reference to the identifier of the payment 
	 *      that was made.
	 * @throws	BuyTicketRequestException
	 * 			If any input data in the request is not valid.
	 * @throws	PayErrorException
	 * 			If any error occurred while paying.
	 */
	buyTicket (request: BuyTicketRequest): ticket.Ticket;
}

As with Ticket and Rate objects, the BuyTicketRequest object is defined as a plain Wing struct relying on the automatic conversion infrastructure described above.

The ForParkingCars is defined as the Wing interface. Unlike the original “Blue Zone” implementation, this one does not include BuyTicketRequest validation in the port specification. This was done on purpose.

While strong object encapsulation would encourage including the validate() method in the BuyTicketRequest class, with open immutable data structures like the ones adopted here, it could be done where it belongs - in the use case implementation. On the other hand, including the request validation logic in port specification brings in too many implementation details, too early.

ForAdministering Port​

This one is used for providing testFixture functionality, and while it is long, it is also completely straightforward:

bring "./Rate.w" as rate;
bring "./Ticket.w" as ticket;
bring "./ForPaying.w" as forPaying;

/**
 * DRIVING PORT (Provided Interface)
 * For doing administration tasks like initializing, load data in the repositories,
 * configuring the services used by the app, etc.
 * Typically, it is used by:
 *      - Tests (driving actors) for setting up the test-fixture (driven actors).
 *      - The start-up for initializing the app.
 */
 pub inflight interface ForAdministering {

    /**
    * Load the given rates into the data repository,
    * deleting previously existing rates if any.
    */
    initializeRates(newRates: Array<rate.Rate>): void;

    /**
    * Load the given tickets into the data repository,
    * deleting previously existing tickets if any.
    */
    initializeTickets(newTickets: Array<ticket.Ticket>): void;

    /**
    * Make the given ticket code the next to be returned when asking for it.
    */
    changeNextTicketCode(newNextTicketCode: str): void;

    /**
    * Return the ticket stored in the repository with the given code
    */
    getStoredTicket(ticketCode: str): ticket.Ticket;

    /**
    * Return the last request done to the "pay" method
    */
    getLastPayRequest(): forPaying.PayRequest;

    /**
    * Return the last response returned by the "pay" method.
    * It is an identifier of the payment made.
    */
    getLastPayResponse(): str;

    /**
    * Make the probability of a payment error the "percentage" given as a parameter
    */
    setPaymentError(errorCode: forPaying.PaymentError): void;

    /**
    * Return the code of the error that occurred when running the "pay" method
    */
    getPaymentError(): forPaying.PaymentError;

    /**
    * Set the given date-time as the current date-time
    */
    changeCurrentDateTime(newCurrentDateTime: std.Datetime): void;

}

Now, we need to dive one level deeper and look at the application logic implementation.

Implementation Details

ForParkingCarsBackend​

bring "../../application/ports" as ports;
bring "../../application/usecases" as usecases;

pub class ForParkingCarsBackend impl ports.ForParkingCars {
    _buyTicket: usecases.BuyTicket;
    _getAvailableRates: usecases.GetAvailableRates;

    new(
        dataRepository: ports.ForStoringData,
        paymentService: ports.ForPaying,
        dateTimeService: ports.ForObtainingDateTime
    ) {
        this._buyTicket = new usecases.BuyTicket(dataRepository, paymentService, dateTimeService);
        this._getAvailableRates = new usecases.GetAvailableRates(dataRepository);
    }

    pub inflight getAvailableRates(): Set<ports.Rate> {
        return this._getAvailableRates.apply();
    }

    pub inflight buyTicket(request: ports.BuyTicketRequest): ports.Ticket {
        return this._buyTicket.apply(request);
    }
}

This class resides in the src/outside/backend folder and provides an implementation of the ports.ForParkingCars interface that is suitable for a direct function call. As we can see, it assumes two additional Secondary Ports: ports.ForStoringData and ports.ForObtainingTime and delegates actual implementation to two Use Case implementations: BuyTicket and GetAvailableRates. The BuyTicket Use Case implementation is where the core system logic resides, so let’s look at it.

BuyTicket Use Case​

bring math;
bring datetimex;
bring exception;
bring "../ports" as ports;
bring "./Verifier.w" as validate;

pub class BuyTicket {
    _dataRepository: ports.ForStoringData;
    _paymentService: ports.ForPaying;
    _dateTimeService: ports.ForObtainingDateTime;

    new(
        dataRepository: ports.ForStoringData,
        paymentService: ports.ForPaying,
        dateTimeService: ports.ForObtainingDateTime
    ) {
        this._dataRepository = dataRepository;
        this._paymentService = paymentService;
        this._dateTimeService = dateTimeService;    
    }

    pub inflight apply(request: ports.BuyTicketRequest): ports.Ticket {
        let currentDateTime = this._dateTimeService.getCurrentDateTime();
        this._validateRequest(request, currentDateTime);
        let paymentId = this._paymentService.pay(
            euros: request.euros,
            card: request.card
        );
        let ticket = this._buildTicket(request, paymentId, currentDateTime);
        this._dataRepository.saveTicket(ticket);
        return ticket;    
    }

    inflight _validateRequest(request: ports.BuyTicketRequest, currentDateTime: std.Datetime): void {
        let requestErrors = validate.BuyTicketRequest(request, currentDateTime);
        if requestErrors.length > 0 {
            throw exception.ValueError(
                "Buy ticket request is not valid",
                requestErrors
            );
        }
    }

    inflight _buildTicket(
        request: ports.BuyTicketRequest, 
        paymentId: str, 
        currentDateTime: std.Datetime
    ): ports.Ticket {
        let ticketCode = this._dataRepository.nextTicketCode();
        let rate = this._dataRepository.getRateByName(request.rateName);
        let endingDateTime = BuyTicket._calculateEndingDateTime(
            currentDateTime, 
            request.euros, 
            rate.eurosPerHour
        );
        return ports.Ticket {
            ticketCode: ticketCode,
            carPlate: request.carPlate,
            rateName: request.rateName,
            startingDateTime: currentDateTime,
            endingDateTime: endingDateTime,
            price: request.euros,
            paymentId: paymentId
        };
    }
    
    /**
     * minutes = (euros * minutesPerHour) / eurosPerHour
     * endingDateTime = startingDateTime + minutes
     */
     static inflight _calculateEndingDateTime(
        startingDateTime: std.Datetime, 
        euros: num, 
        eurosPerHour: num
    ): std.Datetime {
        let MINUTES_PER_HOUR = 60;
        let minutes = math.round((MINUTES_PER_HOUR * euros) / eurosPerHour);
        return datetimex.plus(startingDateTime, duration.fromMinutes(minutes));
    }
}

The “Buy Ticket” Use Case implementation class resides within the src/application/usescases folder. It returns an inflight function responsible for executing the Use Case logic:

1. Validate Request
2. Pay for a new Ticket
3. Create the Ticket record
4. Store the Ticket record in the database

The main reason for implementing Use Cases as inflight functions is that all Wing event handlers are inflight functions. While direct function calls are useful for local testing, they will typically be HTTP REST or GraphQL API calls in a real deployment.

The actual validation of the BuyTicketRequest is delegated to an auxiliary Util class within the Verifier.w module. The main reason is that individual field validation might be very detailed and involve many low-level specifics, contributing little to the overall use case logic understanding.

Pulling all Components Together

Following the “Hexagonal Architecture Explained” book recommendations, this is implemented within a Configurator class as follows:

bring util;
bring endor;
bring "./outside" as outside;
bring "./application/ports" as ports;

enum ApiType {
    DIRECT_CALL,
    HTTP_REST
}

enum ProgramType {
    UNKNOWN,
    TEST,
    SERVICE
}

pub class Configurator impl outside.BlueZoneApiFactory {
    _apiFactory: outside.BlueZoneApiFactory;

    new(name: str) {
        let mockService = new outside.mock.MockDataRepository();
        let programType = this._getProgramType(name);
        let mode = this._getMode(programType);
        let apiType = this._getApiType(programType, mode);
        this._apiFactory = this._getApiFactory(
            name,
            mode, 
            apiType,
            mockService,
            mockService,
            mockService
        );
    }

    _getProgramType(name: str): ProgramType { //TODO: migrate to endor??
        if name.endsWith("Test") {
            return ProgramType.TEST;
        } elif name.endsWith("Service") || name.endsWith("Application") {
            return ProgramType.SERVICE;
        } elif std.Node.of(this).app.isTestEnvironment {
            return ProgramType.TEST;
        }
        return ProgramType.UNKNOWN;
    }

    _getMode(programType: ProgramType): endor.Mode {
        if let mode = util.tryEnv("MODE") {
            return Map<endor.Mode>{ //TODO Migrate this function to endor
                "DEV" => endor.Mode.DEV,
                "TEST" => endor.Mode.TEST,
                "STAGE" => endor.Mode.STAGE,
                "PROD" => endor.Mode.PROD
            }.get(mode);
        } elif programType == ProgramType.TEST {
            return endor.Mode.TEST;
        } elif programType == ProgramType.SERVICE {
            return endor.Mode.STAGE;
        }
        return endor.Mode.DEV;
    }

    _getApiType(
        programType: ProgramType, 
        mode: endor.Mode,
    ): ApiType {
        if let apiType = util.tryEnv("API_TYPE") {
            return Map<ApiType>{
                "DIRECT_CALL" => ApiType.DIRECT_CALL,
                "HTTP_REST" => ApiType.HTTP_REST
            }.get(apiType);
        } elif programType == ProgramType.SERVICE {
            return ApiType.HTTP_REST;
        }
        let target = util.env("WING_TARGET");
        if target.contains("sim") {
            return ApiType.DIRECT_CALL;
        }
        return ApiType.HTTP_REST;        
    }

    _getApiFactory(
        name: str, 
        mode: endor.Mode,
        apiType: ApiType,
        dataService: ports.ForStoringData,
        paymentService: ports.ForPaying,
        dateTimeService: ports.ForObtainingDateTime
    ): outside.BlueZoneApiFactory {
        let directCall = new outside.DirectCallApiFactory(
            dataService, 
            paymentService, 
            dateTimeService
        );
        if apiType == ApiType.DIRECT_CALL {
            return directCall;
        } elif apiType == ApiType.HTTP_REST {
            return new outside.HttpRestApiFactory(
                name,
                mode,
                directCall
            );
        }
    }

    pub getForAdministering(): ports.ForAdministering {
        return this._apiFactory.getForAdministering();
    }

    pub getForParkingCars(): ports.ForParkingCars {
        return this._apiFactory.getForParkingCars();
    }

    pub getForIssuingFines(): ports.ForIssuingFines {
        return this._apiFactory.getForIssuingFines();
    }

}