Add an examples directory, with a first example of a simple express server

examples/express-server/ConfigSchema.pkl

@@ -0,0 +1,2 @@
+address: String
+port: Int16

examples/express-server/README.md

@@ -0,0 +1,32 @@
+# PklTypescript Example: Express server
+
+This is an example of a simple TypeScript program that uses Pkl for configuration.
+
+## Hand-written code
+
+A summary of each of the files in this directory, and what they do:
+
+- `index.ts`: contains the source code of the express app
+- `ConfigSchema.pkl`: contains the schema of the configuration (just the properties and their types, but not any values)
+- `config.dev.pkl`: amends `ConfigSchema.pkl`, adding the config values that would be used in local development
+- `config.prod.pkl`: amends `ConfigSchema.pkl` but with values to be used in production
+
+## Generated code
+
+There is also another directory, `generated`, that contains `.pkl.ts` files that were generated by `pkl-gen-typescript` based on the given schema.
+
+The `package.json` has a script, titled `gen-config` (but the script name doesn't matter), that executes the following:
+
+```bash
+pkl-gen-typescript ./ConfigSchema.pkl -o ./generated
+```
+
+This uses the `pkl-gen-typescript` CLI, passing in `ConfigSchema.pkl` as the Pkl module to be evaluated, and outputting the generated TypeScript files to the `./generated` directory.
+
+## Running the app
+
+1. Run `npm install` in this directory to install dependencies (including a local link to the `pkl-typescript` project at the root of this repo)
+1. Run `npm run gen-config` to make sure the generated `.pkl.ts` files in the `./generated` directory are up-to-date
+1. Run `npm run start` to start the local dev server
+
+Then, in another terminal, run `curl localhost:3003` to see a response from your Pkl-configured Express server.

examples/express-server/config.dev.pkl

@@ -0,0 +1,4 @@
+amends "ConfigSchema.pkl"
+
+address = "localhost"
+port = 3003

examples/express-server/config.prod.pkl

@@ -0,0 +1,4 @@
+amends "ConfigSchema.pkl"
+
+address = "example.com"
+port = 443

examples/express-server/generated/config_schema.pkl.ts

@@ -0,0 +1,24 @@
+// This file was generated by `pkl-typescript` from Pkl module `ConfigSchema`.
+// DO NOT EDIT.
+import * as pklTypescript from "@pkl-community/pkl-typescript"
+
+// Ref: Module root.
+export interface ConfigSchema {
+  address: string
+
+  port: number
+}
+
+// LoadFromPath loads the pkl module at the given path and evaluates it into a ConfigSchema
+export const loadFromPath = async (path: string): Promise<ConfigSchema> => {
+  const evaluator = await pklTypescript.newEvaluator(pklTypescript.PreconfiguredOptions);
+  try {
+    const result = await load(evaluator, pklTypescript.FileSource(path));
+    return result
+  } finally {
+    evaluator.close()
+  }
+};
+
+export const load = (evaluator: pklTypescript.Evaluator, source: pklTypescript.ModuleSource): Promise<ConfigSchema> =>
+  evaluator.evaluateModule(source) as Promise<ConfigSchema>;

examples/express-server/index.ts

@@ -0,0 +1,21 @@
+import express from "express";
+import { loadFromPath } from "./generated/config_schema.pkl";
+
+const app = express();
+
+app.get("/", (_, res) => {
+  res.send("Hello from a pkl-configured app!");
+});
+
+// The config file to evaluate can be dynamically chosen based on the value of NODE_ENV
+const configFile = `config.${process.env.NODE_ENV ?? "dev"}.pkl`;
+
+// Use pkl-typescript to load and evaluate the selected Pkl file
+loadFromPath(configFile).then((config) => {
+  console.log("Loaded config values from Pkl:", JSON.stringify(config));
+
+  // `config` is a typed object, of the schema given in ConfigSchema.pkl
+  app.listen(config.port, config.address, () => {
+    console.log("Server started");
+  });
+});