@dbos-inc/create 1.29.4-preview → 1.29.11-preview

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dbos-inc/create",
-  "version": "1.29.4-preview",
+  "version": "1.29.11-preview",
   "description": "Tool for performing project initialization from template",
   "license": "MIT",
   "type": "module",

package/templates/hello/README.md

@@ -14,7 +14,21 @@ node start_postgres_docker.js
 
 If successful, the script should print `Database started successfully!`.
 
-Next, build the app:
+Next, you can build and run the app in one step under `nodemon`:
+
+```bash
+npm run dev
+```
+
+To see that it's working, visit this URL in your browser: [`http://localhost:3000/greeting/dbos`](http://localhost:3000/greeting/dbos).
+You should get this message: `Hello, dbos! You have been greeted 1 times.`
+Each time you refresh the page, the counter should go up by one!
+
+Congratulations! You just launched a DBOS application.
+
+## Production build
+
+In production, instead of using `nodemon`, the following separate steps should be used to build, run database setup, and start the app.
 
 ```bash
 npm run build
@@ -34,15 +48,27 @@ Finally, run the app:
 npx dbos-sdk start
 ```
 
-To see that it's working, visit this URL in your browser: [`http://localhost:3000/greeting/dbos`](http://localhost:3000/greeting/dbos).
-You should get this message: `Hello, dbos! You have been greeted 1 times.`
-Each time you refresh the page, the counter should go up by one!
+## The application
 
-Congratulations! You just launched a DBOS application.
+The core of the application resides in `src/operations.ts`. It declares an "hello world" DBOS workflow served at `/greetings/:user`. To add more functionality, modify `src/operations.ts`. If you used `npm run dev`, it will automatically rebuild and restart.
+
+## Running in DBOS Cloud
+
+To deploy this app to DBOS Cloud, first install the DBOS Cloud CLI (example with [npm](https://www.npmjs.com/)):
+
+```shell
+npm i -g @dbos-inc/dbos-cloud
+```
+
+Then, run this command to deploy your app:
+
+```shell
+dbos-cloud app deploy
+```
+
+functionality to this application, modify `src/operations.ts`. If you used `npm run dev`, it will automatically rebuild and restart.
 
 ## Next Steps
 
-- To add more functionality to this application, modify `src/operations.ts`, then rebuild and restart it.  Alternatively, `npm run dev` uses `nodemon` to automatically rebuild and restart the app when source files change, using instructions specified in `nodemon.json`.
 - For a detailed tutorial, check out our [programming quickstart](https://docs.dbos.dev/getting-started/quickstart-programming).
-- To learn how to deploy your application to DBOS Cloud, visit our [cloud quickstart](https://docs.dbos.dev/getting-started/quickstart-cloud/)
 - To learn more about DBOS, take a look at [our documentation](https://docs.dbos.dev/) or our [source code](https://github.com/dbos-inc/dbos-transact).

package/templates/hello/src/operations.ts

@@ -4,8 +4,8 @@
 // It greets visitors and keeps track of how many times each visitor has been greeted.
 // To run this app, visit our Quickstart: https://docs.dbos.dev/getting-started/quickstart
 
-import { HandlerContext, TransactionContext, Transaction, GetApi, ArgSource, ArgSources } from '@dbos-inc/dbos-sdk';
-import { Knex } from 'knex';
+import { HandlerContext, TransactionContext, Transaction, GetApi, ArgSource, ArgSources } from "@dbos-inc/dbos-sdk";
+import { Knex } from "knex";
 
 // The schema of the database table used in this example.
 export interface dbos_hello {
@@ -14,10 +14,10 @@ export interface dbos_hello {
 }
 
 export class Hello {
-
   // Serve this function from HTTP GET requests at the /greeting endpoint with 'user' as a path parameter
-  @GetApi('/greeting/:user')
-  @Transaction()  // Run this function as a database transaction
+  // The @Transaction() decorator ensures that this function runs as a database transaction.
+  @GetApi("/greeting/:user")
+  @Transaction() // Run this function as a database transaction
   static async helloTransaction(ctxt: TransactionContext<Knex>, @ArgSource(ArgSources.URL) user: string) {
     // Retrieve and increment the number of times this user has been greeted.
     const query = "INSERT INTO dbos_hello (name, greet_count) VALUES (?, 1) ON CONFLICT (name) DO UPDATE SET greet_count = dbos_hello.greet_count + 1 RETURNING greet_count;";
@@ -27,6 +27,8 @@ export class Hello {
     return Hello.makeHTML(greeting);
   }
 
+  // Let's declare helper functions to serve static HTML
+
   // Serve a quick readme for the app at the / endpoint
   @GetApi('/')
   static async readme(_ctxt: HandlerContext) {

package/templates/hello-express/README.md

@@ -0,0 +1,75 @@
+# DBOS Hello
+
+This is a [DBOS app](https://docs.dbos.dev/) bootstrapped with `npx @dbos-inc/create`, using [Express.js](https://expressjs.com/) and [Knex](https://docs.dbos.dev/tutorials/using-knex) to interact with postgres.
+
+## Getting Started
+
+Before you can launch your app, you need a database.
+DBOS works with any Postgres database, but to make things easier, we've provided a script that starts a Docker Postgres container and creates a database.
+Run:
+
+```bash
+node start_postgres_docker.js
+```
+
+If successful, the script should print `Database started successfully!`.
+
+Next, you can build and run the app in one step under `nodemon`:
+
+```bash
+npm run dev
+```
+
+To see that it's working, visit this URL in your browser: [`http://localhost:3000/greeting/dbos`](http://localhost:3000/greeting/dbos).
+You should get this message: `Hello, dbos! You have been greeted 1 times.`
+Each time you refresh the page, the counter should go up by one!
+
+Congratulations! You just launched a DBOS application.
+
+## Production build
+
+In production, instead of using `nodemon`, the following separate steps should be used to build, run database setup, and start the app.
+
+```bash
+npm run build
+```
+
+Then, run a schema migration to create some tables:
+
+```bash
+npx dbos-sdk migrate
+```
+
+If successful, the migration should print `Migration successful!`.
+
+Finally, run the app:
+
+```bash
+npx dbos-sdk start
+```
+
+## The application
+
+- In `src/operations.ts`, the Express app object is created and configured to serve an "hello world" DBOS workflow on `/greetings/:user`. This file also hosts the code of said DBOS workflow: an `Hello` class with a single `helloTransaction` method.
+- `src/main.ts` declares the code to start a DBOS instance and an Express application. When you pass the Express app object as parameter to `DBOS.launch()`, DBOS will wrap all routes with an [OpenTelemetry](https://opentelemetry.io/) tracing middleware and tie HTTP traces to DBOS workflow traces.
+
+To add more functionality to this application, modify `src/operations.ts`. If you used `npm run dev`, it will automatically rebuild and restart.
+
+## Running in DBOS Cloud
+
+To deploy this app to DBOS Cloud, first install the DBOS Cloud CLI (example with [npm](https://www.npmjs.com/)):
+
+```shell
+npm i -g @dbos-inc/dbos-cloud
+```
+
+Then, run this command to deploy your app:
+
+```shell
+dbos-cloud app deploy
+```
+
+## Next Steps
+
+- For a detailed tutorial, check out our [programming quickstart](https://docs.dbos.dev/getting-started/quickstart-programming).
+- To learn more about DBOS, take a look at [our documentation](https://docs.dbos.dev/) or our [source code](https://github.com/dbos-inc/dbos-transact).

package/templates/hello-express/dbos-config.yaml

@@ -0,0 +1,20 @@
+# To enable auto-completion and validation for this file in VSCode, install the RedHat YAML extension
+# https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml
+
+# yaml-language-server: $schema=https://raw.githubusercontent.com/dbos-inc/dbos-transact/main/dbos-config.schema.json
+
+language: node
+database:
+  hostname: localhost
+  port: 5432
+  username: postgres
+  password: ${PGPASSWORD}
+  connectionTimeoutMillis: 3000
+  app_db_client: knex
+  migrate:
+    - npx knex migrate:latest
+  rollback:
+    - npx knex migrate:rollback
+runtimeConfig:
+  start:
+    - dist/main.js

package/templates/hello-express/eslint.config.js

@@ -0,0 +1,28 @@
+const { FlatCompat } = require("@eslint/eslintrc");
+const dbosIncEslintPlugin = require("@dbos-inc/eslint-plugin");
+const typescriptEslint = require("typescript-eslint");
+const typescriptEslintParser = require("@typescript-eslint/parser");
+const globals = require("globals");
+const js = require("@eslint/js");
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended
+});
+
+module.exports = typescriptEslint.config({
+  extends: compat.extends("plugin:@dbos-inc/dbosRecommendedConfig"),
+  plugins: { "@dbos-inc": dbosIncEslintPlugin },
+
+  languageOptions: {
+    parser: typescriptEslintParser,
+    parserOptions: { project: "./tsconfig.json" },
+    globals: { ...globals.node, ...globals.es6 }
+  },
+
+  rules: {
+    "no-secrets/no-secrets": ["error", { "tolerance": 5 }]
+  },
+
+  ignores: ["**/*.test.ts"]
+});

package/templates/hello-express/gitignore.template

@@ -0,0 +1,144 @@
+# DBOS-specific
+.dbos
+
+# Logs
+**/.DS_Store
+**/prisma/migrations/*
+
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+dbos_deploy/
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# VSCode settings
+.vscode/settings.json
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# Editor temp/recovery files
+*.swp
+*.swo

package/templates/hello-express/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testRegex: '((\\.|/)(test|spec))\\.ts?$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  modulePaths: ["./"],
+};

package/templates/hello-express/knexfile.js

@@ -0,0 +1,20 @@
+const { parseConfigFile } = require('@dbos-inc/dbos-sdk');
+
+const [dbosConfig, ] = parseConfigFile();
+
+const config = {
+  client: 'pg',
+  connection: {
+    host: dbosConfig.poolConfig.host,
+    port: dbosConfig.poolConfig.port,
+    user: dbosConfig.poolConfig.user,
+    password: dbosConfig.poolConfig.password,
+    database: dbosConfig.poolConfig.database,
+    ssl: dbosConfig.poolConfig.ssl,
+  },
+  migrations: {
+    directory: './migrations'
+  }
+};
+
+module.exports = config;

package/templates/hello-express/migrations/20240212161006_create_dbos_hello_tables.js

@@ -0,0 +1,18 @@
+const { Knex } = require("knex");
+
+exports.up = async function(knex) {
+  await knex.schema.createTable('dbos_hello', table => {
+    table.text('name').primary();
+    table.integer('greet_count').defaultTo(0);
+  });
+
+  return knex.schema.createTable('dbos_greetings', table => {
+    table.text('greeting_name');
+    table.text('greeting_note_content');
+  });
+};
+
+exports.down = async function(knex) {
+  await knex.schema.dropTable('dbos_greetings');
+  return knex.schema.dropTable('dbos_hello');
+};

package/templates/hello-express/nodemon.json

@@ -0,0 +1,7 @@
+{
+  "watch": ["src/","migrations/"],
+  "ext": "ts,json",
+  "ignore": ["src/**/*.test.ts"],
+  "exec": "npm run build && npx dbos migrate && node dist/main.js"
+}
+

package/templates/hello-express/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "dbos-hello-express",
+  "version": "0.0.1",
+  "scripts": {
+    "build": "tsc",
+    "test": "npx dbos rollback && npx dbos migrate && jest",
+    "dev": "nodemon",
+    "start": "npx dbos start"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/supertest": "^2.0.16",
+    "jest": "^29.7.0",
+    "nodemon": "^3.1.0",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.5"
+  },
+  "dependencies": {
+    "@dbos-inc/dbos-sdk": "file:../../../..",
+    "express": "^4.21.1",
+    "knex": "3.1.0"
+  }
+}

package/templates/hello-express/src/main.test.ts

@@ -0,0 +1,36 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { app, dbos_hello, Hello } from "./operations";
+import request from "supertest";
+
+describe("operations-test", () => {
+  beforeAll(async () => {
+    await DBOS.launch({expressApp: app});
+  });
+
+  afterAll(async () => {
+    await DBOS.shutdown();
+  });
+
+  /**
+   * Test the transaction.
+   */
+  test("test-transaction", async () => {
+    const res = await Hello.helloTransaction("dbos");
+    expect(res).toMatch("Hello, dbos! You have been greeted");
+
+    // Check the greet count.
+    const rows = await DBOS.executor.queryUserDB("SELECT * FROM dbos_hello WHERE name=$1", ["dbos"]) as dbos_hello[];
+    expect(rows[0].greet_count).toBe(1);
+  });
+
+  /**
+   * Test the HTTP endpoint.
+   */
+  test("test-endpoint", async () => {
+    const res = await request(app).get(
+      "/greeting/dbos"
+    );
+    expect(res.statusCode).toBe(200);
+    expect(res.text).toMatch("Hello, dbos! You have been greeted");
+  });
+});

package/templates/hello-express/src/main.ts

@@ -0,0 +1,16 @@
+import { app } from './operations';
+import { DBOS } from '@dbos-inc/dbos-sdk';
+
+async function main() {
+  await DBOS.launch({expressApp: app});
+
+  const PORT = DBOS.runtimeConfig?.port ?? 3000;
+  const ENV = process.env.NODE_ENV || 'development';
+
+  app.listen(PORT, () => {
+    console.log(`🚀 Server is running on http://localhost:${PORT}`);
+    console.log(`🌟 Environment: ${ENV}`);
+  });
+}
+
+main().catch(console.log);

package/templates/hello-express/src/operations.ts

@@ -0,0 +1,81 @@
+// Welcome to DBOS!
+
+// This is a sample "Hello" app built with DBOS, Express.js, and Knex.
+// It greets visitors and keeps track of how many times each visitor has been greeted.
+
+// First let's import express and DBOS
+import express from "express";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+// Then, let's declare a type representing the "dbos_hello" database table
+export interface dbos_hello {
+  name: string;
+  greet_count: number;
+}
+
+// Now let's define a class with some static functions.
+// DBOS uses TypeScript decorators to automatically make your functions reliable, so they need to be static.
+export class Hello {
+  // This function greets a user and increments the greet count in the database.
+  // The @DBOS.transaction() decorator ensures that this function runs as a database transaction.
+  @DBOS.transaction()
+  static async helloTransaction(user: string) {
+    const query = "INSERT INTO dbos_hello (name, greet_count) VALUES (?, 1) ON CONFLICT (name) DO UPDATE SET greet_count = dbos_hello.greet_count + 1 RETURNING greet_count;";
+    const { rows } = (await DBOS.knexClient.raw(query, [user])) as { rows: dbos_hello[] };
+    const greet_count = rows[0].greet_count;
+    const greeting = `Hello, ${user}! You have been greeted ${greet_count} times.`;
+    return Hello.makeHTML(greeting);
+  }
+
+  // Finally, we will declare helper functions to serve static HTML to user.s
+
+  static async readme() {
+    const message = Hello.makeHTML(
+      `Visit the route <code class="bg-gray-100 px-1 rounded">/greeting/{name}</code> to be greeted!<br>
+      For example, visit <code class="bg-gray-100 px-1 rounded"><a href="/greeting/Mike" class="text-blue-600 hover:underline">/greeting/Mike</a></code><br>
+      The counter increments with each page visit.`
+    );
+    return Promise.resolve(message);
+  }
+
+  // A helper function to create HTML pages with some styling
+  static makeHTML(message: string) {
+    const page = `
+      <!DOCTYPE html>
+      <html lang="en">
+      <head>
+          <title>DBOS Template App</title>
+          <script src="https://cdn.tailwindcss.com"></script>
+      </head>
+      <body class="font-sans text-gray-800 p-6 max-w-2xl mx-auto">
+          <h1 class="text-3xl font-semibold mb-4">Welcome to DBOS!</h1>
+          <p class="mt-8 mb-8">` + message + `</p>
+          <p class="mb-2">
+              To learn how to run this app yourself, visit our
+              <a href="https://docs.dbos.dev/quickstart?language=typescript" class="text-blue-600 hover:underline">Quickstart</a>.
+          </p><p class="mb-2">
+              Then, to learn how to build crashproof apps, continue to our
+              <a href="https://docs.dbos.dev/typescript/programming-guide" class="text-blue-600 hover:underline">Programming Guide</a>.<br>
+          </p>
+      </body>
+      </html>`;
+    return page;
+  }
+}
+
+// Now, let's create an Express app and define some routes.
+export const app = express();
+// Parse JSON payloads and make it available to req.body
+app.use(express.json());
+
+// We'll serve the README at the root of the app
+app.get("/", async (_, res) => {
+  res.send(await Hello.readme());
+});
+
+// Serve this function from HTTP GET requests at the /greeting endpoint with 'user' as a path parameter
+// The handler will in turn call a reliable DBOS operation (helloTransaction) to greet the user
+app.get("/greeting/:user", async (req, res) => {
+  const { user } = req.params;
+  res.send(await Hello.helloTransaction(user));
+});

package/templates/hello-express/start_postgres_docker.js

@@ -0,0 +1,40 @@
+const { execSync } = require('child_process');
+
+// Default PostgreSQL port
+let port = '5432';
+
+// Set the host PostgreSQL port with the -p/--port flag.
+process.argv.forEach((val, index) => {
+  if (val === '-p' || val === '--port') {
+    if (process.argv[index + 1]) {
+      port = process.argv[index + 1];
+    }
+  }
+});
+
+if (!process.env.PGPASSWORD) {
+  console.error("Error: PGPASSWORD is not set.");
+  process.exit(1);
+}
+
+try {
+  execSync(`docker run --rm --name=dbos-db --env=POSTGRES_PASSWORD="${process.env.PGPASSWORD}" --env=PGDATA=/var/lib/postgresql/data --volume=/var/lib/postgresql/data -p ${port}:5432 -d sibedge/postgres-plv8`);
+  console.log("Waiting for PostgreSQL to start...");
+
+  let attempts = 30;
+  const checkDatabase = setInterval(() => {
+    try {
+      execSync('docker exec dbos-db psql -U postgres -c "SELECT 1;"', { stdio: 'ignore' });
+      console.log("PostgreSQL started!");
+      clearInterval(checkDatabase);
+      console.log("Database started successfully!");
+    } catch (error) {
+      if (--attempts === 0) {
+        clearInterval(checkDatabase);
+        console.error("Failed to start PostgreSQL.");
+      }
+    }
+  }, 1000);
+} catch (error) {
+  console.error("Error starting PostgreSQL in Docker:", error.message);
+}

package/templates/hello-express/tsconfig.json

@@ -0,0 +1,25 @@
+/* Visit https://aka.ms/tsconfig to read more about this file */
+{
+  "compilerOptions": {
+    "target": "esnext",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    "experimentalDecorators": true,                      /* Enable experimental support for legacy experimental decorators. */
+    "emitDecoratorMetadata": true,                       /* Emit design-type metadata for decorated declarations in source files. */
+    "module": "Node16",                                /* Specify what module code is generated. */
+    "declaration": true,                                 /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+    "declarationMap": true,                              /* Create sourcemaps for d.ts files. */
+    "sourceMap": true,                                   /* Create source map files for emitted JavaScript files. */
+    "outDir": "./dist",                                  /* Specify an output folder for all emitted files. */
+    "newLine": "lf",                                     /* Set the newline character for emitting files. */
+    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+    "strict": true,                                      /* Enable all strict type-checking options. */
+    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
+  },
+  "include": [                                           /* Specifies an array of filenames or patterns to include in the program. */
+    "src"
+  ],
+  "exclude": [
+    "**/*.test.ts",
+    "dist"
+  ]
+}

package/templates/hello-v2/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+	// Automatically recommend the DBOS extension to VSCode users.
+	// Documentation on extensions.json: http://go.microsoft.com/fwlink/?LinkId=827846
+	"recommendations": [
+		"dbos-inc.dbos-ttdbg"
+	]
+}

package/templates/hello-v2/.vscode/launch.json

@@ -0,0 +1,21 @@
+{
+    // Automatically configure the VSCode debugger for DBOS projects.
+    // Documentation on launch.json: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+      {
+        "type": "node-terminal",
+        "request": "launch",
+        "name": "Local Debug",
+        "command": "npx dbos start",
+        "preLaunchTask": "npm: build",
+      },
+      {
+        "type": "node-terminal",
+        "request": "launch",
+        "name": "Time Travel Debug",
+        "command": "npx dbos debug -x ${command:dbos-ttdbg.get-proxy-url} -u ${command:dbos-ttdbg.pick-workflow-id}",
+        "preLaunchTask": "npm: build"
+      }
+    ]
+  }

package/templates/hello-v2/.vscode/tasks.json

@@ -0,0 +1,19 @@
+{
+    // Configure the build command for DBOS projects using VSCode.
+    // Documentation on tasks.json: https://code.visualstudio.com/docs/editor/tasks
+    "version": "2.0.0",
+    "tasks": [
+      {
+        "label": "npm: build",
+        "type": "npm",
+        "script": "build",
+        "group": {
+          "kind": "build",
+          "isDefault": true
+        },
+        "problemMatcher": [
+          "$tsc"
+        ]
+      }
+    ]
+  }

package/templates/hello-v2/README.md

@@ -0,0 +1,55 @@
+# DBOS Hello
+
+This is a [DBOS app](https://docs.dbos.dev/) bootstrapped with `npx @dbos-inc/create` and using [Knex](https://docs.dbos.dev/tutorials/using-knex).
+
+## Getting Started
+
+Before you can launch your app, you need a database.
+DBOS works with any Postgres database, but to make things easier, we've provided a script that starts a Docker Postgres container and creates a database.
+Run:
+
+```bash
+node start_postgres_docker.js
+```
+
+If successful, the script should print `Database started successfully!`.
+
+To build the app, set up the database, and run, in one step:
+```bash
+npm run dev
+```
+This uses `nodemon`, so if you change your app it will automatically restart with changes.
+
+To see that it's working, visit this URL in your browser: [`http://localhost:3000/greeting/dbos`](http://localhost:3000/greeting/dbos).
+You should get this message: `Hello, dbos! You have been greeted 1 times.`
+Each time you refresh the page, the counter should go up by one!
+
+Congratulations! You just launched a DBOS application.
+
+### Separate Build and Run Steps
+
+To build the app:
+```bash
+npm run build
+```
+
+Then, run a schema migration to create some tables:
+
+```bash
+npx dbos-sdk migrate
+```
+
+If successful, the migration should print `Migration successful!`.
+
+Finally, run the app:
+
+```bash
+npx dbos-sdk start
+```
+
+## Next Steps
+
+- To add more functionality to this application, modify `src/operations.ts`, and save it.  If you are using, `npm run dev`, `nodemon` will rebuild and restart the app automatically.
+- For a detailed tutorial, check out our [programming quickstart](https://docs.dbos.dev/getting-started/quickstart-programming).
+- To learn how to deploy your application to DBOS Cloud, visit our [cloud quickstart](https://docs.dbos.dev/getting-started/quickstart-cloud/)
+- To learn more about DBOS, take a look at [our documentation](https://docs.dbos.dev/) or our [source code](https://github.com/dbos-inc/dbos-transact).

package/templates/hello-v2/dbos-config.yaml

@@ -0,0 +1,20 @@
+# To enable auto-completion and validation for this file in VSCode, install the RedHat YAML extension
+# https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml
+
+# yaml-language-server: $schema=https://raw.githubusercontent.com/dbos-inc/dbos-transact/main/dbos-config.schema.json
+
+language: node
+database:
+  hostname: localhost
+  port: 5432
+  username: postgres
+  password: ${PGPASSWORD}
+  connectionTimeoutMillis: 3000
+  app_db_client: knex
+  migrate:
+    - npx knex migrate:latest
+  rollback:
+    - npx knex migrate:rollback
+runtimeConfig:
+  entrypoints:
+    - dist/operations.js

package/templates/hello-v2/eslint.config.js

@@ -0,0 +1,28 @@
+const { FlatCompat } = require("@eslint/eslintrc");
+const dbosIncEslintPlugin = require("@dbos-inc/eslint-plugin");
+const typescriptEslint = require("typescript-eslint");
+const typescriptEslintParser = require("@typescript-eslint/parser");
+const globals = require("globals");
+const js = require("@eslint/js");
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended
+});
+
+module.exports = typescriptEslint.config({
+  extends: compat.extends("plugin:@dbos-inc/dbosRecommendedConfig"),
+  plugins: { "@dbos-inc": dbosIncEslintPlugin },
+
+  languageOptions: {
+    parser: typescriptEslintParser,
+    parserOptions: { project: "./tsconfig.json" },
+    globals: { ...globals.node, ...globals.es6 }
+  },
+
+  rules: {
+    "no-secrets/no-secrets": ["error", { "tolerance": 5 }]
+  },
+
+  ignores: ["**/*.test.ts"]
+});

package/templates/hello-v2/gitignore.template

@@ -0,0 +1,144 @@
+# DBOS-specific
+.dbos
+
+# Logs
+**/.DS_Store
+**/prisma/migrations/*
+
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+dbos_deploy/
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+.cache
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# VSCode settings
+.vscode/settings.json
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+# Editor temp/recovery files
+*.swp
+*.swo

package/templates/hello-v2/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testRegex: '((\\.|/)(test|spec))\\.ts?$',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  modulePaths: ["./"],
+};

package/templates/hello-v2/knexfile.js

@@ -0,0 +1,20 @@
+const { parseConfigFile } = require('@dbos-inc/dbos-sdk');
+
+const [dbosConfig, ] = parseConfigFile();
+
+const config = {
+  client: 'pg',
+  connection: {
+    host: dbosConfig.poolConfig.host,
+    port: dbosConfig.poolConfig.port,
+    user: dbosConfig.poolConfig.user,
+    password: dbosConfig.poolConfig.password,
+    database: dbosConfig.poolConfig.database,
+    ssl: dbosConfig.poolConfig.ssl,
+  },
+  migrations: {
+    directory: './migrations'
+  }
+};
+
+module.exports = config;

package/templates/hello-v2/migrations/20240212161006_create_dbos_hello_tables.js

@@ -0,0 +1,18 @@
+const { Knex } = require("knex");
+
+exports.up = async function(knex) {
+  await knex.schema.createTable('dbos_hello', table => {
+    table.text('name').primary();
+    table.integer('greet_count').defaultTo(0);
+  });
+
+  return knex.schema.createTable('dbos_greetings', table => {
+    table.text('greeting_name');
+    table.text('greeting_note_content');
+  });
+};
+
+exports.down = async function(knex) {
+  await knex.schema.dropTable('dbos_greetings');
+  return knex.schema.dropTable('dbos_hello');
+};

package/templates/hello-v2/nodemon.json

@@ -0,0 +1,7 @@
+{
+  "watch": ["src/","migrations/"],
+  "ext": "ts,json",
+  "ignore": ["src/**/*.test.ts"],
+  "exec": "npm run build && npx dbos migrate && npm run start"
+}
+

package/templates/hello-v2/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "dbos-hello-v2",
+  "version": "0.0.1",
+  "scripts": {
+    "build": "tsc",
+    "test": "npx dbos rollback && npx dbos migrate && jest",
+    "dev": "nodemon",
+    "start": "npx dbos start"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/supertest": "^2.0.16",
+    "jest": "^29.7.0",
+    "nodemon": "^3.1.0",
+    "supertest": "^7.0.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.5"
+  },
+  "dependencies": {
+    "@dbos-inc/dbos-sdk": "file:../../../..",
+    "knex": "3.1.0"
+  }
+}

package/templates/hello-v2/src/operations.test.ts

@@ -0,0 +1,36 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { Hello, dbos_hello } from "./operations";
+import request from "supertest";
+
+describe("operations-test", () => {
+  beforeAll(async () => {
+    await DBOS.launch();
+  });
+
+  afterAll(async () => {
+    await DBOS.shutdown();
+  });
+
+  /**
+   * Test the transaction.
+   */
+  test("test-transaction", async () => {
+    const res = await Hello.helloTransaction("dbos");
+    expect(res).toMatch("Hello, dbos! You have been greeted");
+
+    // Check the greet count.
+    const rows = await DBOS.executor.queryUserDB("SELECT * FROM dbos_hello WHERE name=$1", ["dbos"]) as dbos_hello[];
+    expect(rows[0].greet_count).toBe(1);
+  });
+
+  /**
+   * Test the HTTP endpoint.
+   */
+  test("test-endpoint", async () => {
+    const res = await request(DBOS.getHTTPHandlersCallback()).get(
+      "/greeting/dbos"
+    );
+    expect(res.statusCode).toBe(200);
+    expect(res.text).toMatch("Hello, dbos! You have been greeted");
+  });
+});

package/templates/hello-v2/src/operations.ts

@@ -0,0 +1,64 @@
+// Welcome to DBOS!
+
+// This is a sample "Hello" app built with DBOS.
+// It greets visitors and keeps track of how many times each visitor has been greeted.
+
+// First, let's import DBOS
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+// Then, let's declare a type representing the "dbos_hello" database table
+export interface dbos_hello {
+  name: string;
+  greet_count: number;
+}
+
+// Now let's define a class with some static functions.
+// DBOS uses TypeScript decorators to automatically make your functions reliable, so they need to be static.
+export class Hello {
+  // Serve this function from HTTP GET requests at the /greeting endpoint with 'user' as a path parameter
+  @DBOS.getApi("/greeting/:user")
+  @DBOS.transaction() // Run this function as a database transaction
+  static async helloTransaction(user: string) {
+    // Retrieve and increment the number of times this user has been greeted.
+    const query = "INSERT INTO dbos_hello (name, greet_count) VALUES (?, 1) ON CONFLICT (name) DO UPDATE SET greet_count = dbos_hello.greet_count + 1 RETURNING greet_count;";
+    const { rows } = (await DBOS.knexClient.raw(query, [user])) as { rows: dbos_hello[] };
+    const greet_count = rows[0].greet_count;
+    const greeting = `Hello, ${user}! You have been greeted ${greet_count} times.`;
+    return Hello.makeHTML(greeting);
+  }
+
+  // Serve a quick readme for the app at the / endpoint
+  @DBOS.getApi("/")
+  static async readme() {
+    const message = Hello.makeHTML(
+      `Visit the route <code class="bg-gray-100 px-1 rounded">/greeting/{name}</code> to be greeted!<br>
+      For example, visit <code class="bg-gray-100 px-1 rounded"><a href="/greeting/Mike" class="text-blue-600 hover:underline">/greeting/Mike</a></code><br>
+      The counter increments with each page visit.`
+    );
+    return Promise.resolve(message);
+  }
+
+  // A helper function to create HTML pages with some styling
+  static makeHTML(message: string) {
+    const page = `
+      <!DOCTYPE html>
+      <html lang="en">
+      <head>
+          <title>DBOS Template App</title>
+          <script src="https://cdn.tailwindcss.com"></script>
+      </head>
+      <body class="font-sans text-gray-800 p-6 max-w-2xl mx-auto">
+          <h1 class="text-3xl font-semibold mb-4">Welcome to DBOS!</h1>
+          <p class="mt-8 mb-8">` + message + `</p>
+          <p class="mb-2">
+              To learn how to run this app yourself, visit our
+              <a href="https://docs.dbos.dev/quickstart?language=typescript" class="text-blue-600 hover:underline">Quickstart</a>.
+          </p><p class="mb-2">
+              Then, to learn how to build crashproof apps, continue to our
+              <a href="https://docs.dbos.dev/typescript/programming-guide" class="text-blue-600 hover:underline">Programming Guide</a>.<br>
+          </p>
+      </body>
+      </html>`;
+    return page;
+  }
+}

package/templates/hello-v2/start_postgres_docker.js

@@ -0,0 +1,40 @@
+const { execSync } = require('child_process');
+
+// Default PostgreSQL port
+let port = '5432';
+
+// Set the host PostgreSQL port with the -p/--port flag.
+process.argv.forEach((val, index) => {
+  if (val === '-p' || val === '--port') {
+    if (process.argv[index + 1]) {
+      port = process.argv[index + 1];
+    }
+  }
+});
+
+if (!process.env.PGPASSWORD) {
+  console.error("Error: PGPASSWORD is not set.");
+  process.exit(1);
+}
+
+try {
+  execSync(`docker run --rm --name=dbos-db --env=POSTGRES_PASSWORD="${process.env.PGPASSWORD}" --env=PGDATA=/var/lib/postgresql/data --volume=/var/lib/postgresql/data -p ${port}:5432 -d sibedge/postgres-plv8`);
+  console.log("Waiting for PostgreSQL to start...");
+
+  let attempts = 30;
+  const checkDatabase = setInterval(() => {
+    try {
+      execSync('docker exec dbos-db psql -U postgres -c "SELECT 1;"', { stdio: 'ignore' });
+      console.log("PostgreSQL started!");
+      clearInterval(checkDatabase);
+      console.log("Database started successfully!");
+    } catch (error) {
+      if (--attempts === 0) {
+        clearInterval(checkDatabase);
+        console.error("Failed to start PostgreSQL.");
+      }
+    }
+  }, 1000);
+} catch (error) {
+  console.error("Error starting PostgreSQL in Docker:", error.message);
+}

package/templates/hello-v2/tsconfig.json

@@ -0,0 +1,25 @@
+/* Visit https://aka.ms/tsconfig to read more about this file */
+{
+  "compilerOptions": {
+    "target": "esnext",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    "experimentalDecorators": true,                      /* Enable experimental support for legacy experimental decorators. */
+    "emitDecoratorMetadata": true,                       /* Emit design-type metadata for decorated declarations in source files. */
+    "module": "Node16",                                /* Specify what module code is generated. */
+    "declaration": true,                                 /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+    "declarationMap": true,                              /* Create sourcemaps for d.ts files. */
+    "sourceMap": true,                                   /* Create source map files for emitted JavaScript files. */
+    "outDir": "./dist",                                  /* Specify an output folder for all emitted files. */
+    "newLine": "lf",                                     /* Set the newline character for emitting files. */
+    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+    "strict": true,                                      /* Enable all strict type-checking options. */
+    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
+  },
+  "include": [                                           /* Specifies an array of filenames or patterns to include in the program. */
+    "src"
+  ],
+  "exclude": [
+    "**/*.test.ts",
+    "dist"
+  ]
+}