create-monolayer-app 0.1.2 → 0.2.1

package/template/vendor/kysely-dsql/dsql/raw-statement.test.ts

@@ -0,0 +1,167 @@
+// oxlint-disable max-classes-per-file typescript/no-explicit-any
+import { Kysely, PostgresIntrospector, sql } from "kysely";
+import type {
+  DatabaseConnection,
+  Dialect,
+  DialectAdapter,
+  Driver,
+  RawBuilder,
+  TransactionSettings,
+} from "kysely";
+import {
+  afterAll,
+  beforeAll,
+  describe,
+  expect,
+  expectTypeOf,
+  it,
+  vi,
+} from "vitest";
+
+import { DQSLAdapter } from "./adapter.js";
+import { DSQLQueryCompilerError } from "./query-compiler-error.js";
+import { DSQLQueryCompiler } from "./query-compiler.js";
+import { createDSQLRawStatement } from "./raw-statement.js";
+import type { DSQLRawStatementResult } from "./raw-statement.js";
+
+class SpyDriver implements Driver {
+  readonly acquireConnection = vi.fn<() => Promise<DatabaseConnection>>();
+  readonly releaseConnection = vi.fn<() => Promise<void>>().mockResolvedValue();
+  readonly init = vi.fn<() => Promise<void>>().mockResolvedValue();
+  readonly destroy = vi.fn<() => Promise<void>>().mockResolvedValue();
+  readonly beginTransaction = vi
+    .fn<
+      (
+        connection: DatabaseConnection,
+        settings: TransactionSettings
+      ) => Promise<void>
+    >()
+    .mockResolvedValue();
+  readonly commitTransaction = vi
+    .fn<(connection: DatabaseConnection) => Promise<void>>()
+    .mockResolvedValue();
+  readonly rollbackTransaction = vi
+    .fn<(connection: DatabaseConnection) => Promise<void>>()
+    .mockResolvedValue();
+}
+
+class SpyDialect implements Dialect {
+  readonly driver: SpyDriver;
+
+  constructor(driver: SpyDriver) {
+    this.driver = driver;
+  }
+
+  createDriver(): Driver {
+    return this.driver;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this
+  createQueryCompiler(): DSQLQueryCompiler {
+    return new DSQLQueryCompiler();
+  }
+
+  // oxlint-disable-next-line class-methods-use-this
+  createAdapter(): DialectAdapter {
+    return new DQSLAdapter();
+  }
+
+  // oxlint-disable-next-line class-methods-use-this
+  createIntrospector(database: Kysely<any>): PostgresIntrospector {
+    return new PostgresIntrospector(database);
+  }
+}
+
+const createTestDb = (driver: SpyDriver): Kysely<any> =>
+  new Kysely<any>({
+    dialect: new SpyDialect(driver),
+  });
+
+interface UserRow {
+  readonly id: string;
+  readonly email: string;
+}
+
+describe(createDSQLRawStatement, () => {
+  beforeAll(() => {
+    vi.stubEnv("CLUSTER_ENDPOINT", "example.dsql.us-east-1.on.aws");
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("returns ok: true and a compilable RawBuilder for supported SQL", () => {
+    const driver = new SpyDriver();
+    const testDb = createTestDb(driver);
+    const sqlString = "SELECT id, email FROM users WHERE id = $1";
+
+    const result = createDSQLRawStatement<UserRow>(sqlString);
+
+    expect(result.ok).toBeTruthy();
+    // SAFETY: result.ok is verified truthy above.
+    const okResult = result as Extract<
+      DSQLRawStatementResult<UserRow>,
+      { ok: true }
+    >;
+    const compiled = okResult.query.compile(testDb);
+    expect(compiled.sql).toBe(sqlString);
+    expectTypeOf(okResult.query).toEqualTypeOf<RawBuilder<UserRow>>();
+  });
+
+  it("returns ok: false with validation issues for unsupported SQL", () => {
+    const result = createDSQLRawStatement("TRUNCATE TABLE users;");
+
+    expect(result.ok).toBeFalsy();
+    expect("query" in result).toBeFalsy();
+    // SAFETY: result.ok is verified falsy above.
+    const errResult = result as Extract<
+      DSQLRawStatementResult<unknown>,
+      { ok: false }
+    >;
+    expect(errResult.issues).toStrictEqual([
+      expect.objectContaining({
+        code: "truncate",
+        feature: "Table truncation",
+        documentationUrl: expect.stringMatching(
+          /^https:\/\/docs\.aws\.amazon\.com\/aurora-dsql\//u
+        ),
+      }),
+    ]);
+  });
+
+  it("does not throw for invalid SQL input", () => {
+    expect(() => {
+      createDSQLRawStatement(
+        "ALTER TABLE users ADD CONSTRAINT fk FOREIGN KEY (dept_id) REFERENCES dept(id)"
+      );
+    }).not.toThrow();
+  });
+
+  it("propagates generic type T to RawBuilder<T>", () => {
+    const result = createDSQLRawStatement<{ count: number }>(
+      "SELECT count(*) FROM users"
+    );
+    expectTypeOf(result).toEqualTypeOf<
+      DSQLRawStatementResult<{ count: number }>
+    >();
+    // SAFETY: Type assertion used to test generic propagation on the truthy branch.
+    const okResult = result as Extract<
+      DSQLRawStatementResult<{ count: number }>,
+      { ok: true }
+    >;
+    expectTypeOf(okResult.query).toEqualTypeOf<RawBuilder<{ count: number }>>();
+  });
+
+  it("leaves direct sql.raw protected by DSQLQueryCompiler backstop", async () => {
+    const driver = new SpyDriver();
+    const testDb = createTestDb(driver);
+
+    // Direct sql.raw bypasses createDSQLRawStatement, but the compiler catches it.
+    await expect(
+      sql.raw("DROP MATERIALIZED VIEW active_users").execute(testDb)
+    ).rejects.toThrow(DSQLQueryCompilerError);
+
+    expect(driver.acquireConnection).not.toHaveBeenCalled();
+  });
+});

package/template/vendor/kysely-dsql/dsql/raw-statement.ts

@@ -0,0 +1,51 @@
+import { sql } from "kysely";
+import type { RawBuilder } from "kysely";
+
+import { validateDSQLStatement } from "./query-validation.js";
+import type { DSQLValidationIssue } from "./query-validation.js";
+
+/**
+ * Result of creating a raw Aurora DSQL statement.
+ *
+ * @template T - The result row type for the raw query.
+ */
+export type DSQLRawStatementResult<T> =
+  | { readonly ok: true; readonly query: RawBuilder<T> }
+  | { readonly ok: false; readonly issues: readonly DSQLValidationIssue[] };
+
+/**
+ * Creates a validated raw SQL statement for Amazon Aurora DSQL.
+ *
+ * Do not pass untrusted input to this function. Use Kysely parameters for dynamic query values.
+ *
+ * This function validates the SQL string against Aurora DSQL compatibility rules.
+ * It returns a raw query builder when the SQL is valid.
+ * It returns validation issues without throwing an error when the SQL is invalid.
+ *
+ * @template T - The expected query result row type.
+ * @param statement - The raw SQL statement string to validate and build.
+ * @returns A result object containing either the raw query builder or validation issues.
+ * @example
+ * ```ts
+ * const result = createDSQLRawStatement<Person>("SELECT id, name FROM person");
+ * if (result.ok) {
+ *   const query = result.query;
+ * }
+ * ```
+ */
+export function createDSQLRawStatement<T = unknown>(
+  statement: string
+): DSQLRawStatementResult<T> {
+  const validation = validateDSQLStatement(statement);
+  if (!validation.supported) {
+    return {
+      ok: false,
+      issues: validation.issues,
+    };
+  }
+
+  return {
+    ok: true,
+    query: sql.raw<T>(statement),
+  };
+}

package/template/vendor/kysely-dsql/dsql/schema-module.ts

@@ -0,0 +1,167 @@
+import { SchemaModule } from "kysely";
+import type { KyselyPlugin } from "kysely";
+
+import type { DSQLAlterTableBuilder } from "./alter-table-builders.js";
+import type { DSQLCreateTableBuilder } from "./create-table-builder.js";
+import type {
+  DSQLCreateIndexBuilder,
+  DSQLCreateViewBuilder,
+  DSQLDropIndexBuilder,
+  DSQLDropTableBuilder,
+} from "./index-view-builders.js";
+
+/**
+ * Supplies Kysely schema builders with the Aurora DSQL column type contract.
+ *
+ * @example
+ * ```ts
+ * const schema = db.schema;
+ * ```
+ */
+// eslint-disable-next-line max-classes-per-file
+export class DSQLSchemaModule extends SchemaModule {
+  /**
+   * Adds a plugin and keeps the restricted schema module.
+   *
+   * @param plugin - The Kysely plugin.
+   * @returns A restricted schema module with the plugin.
+   * @example
+   * ```ts
+   * const schema = db.schema.withPlugin(plugin);
+   * ```
+   */
+  // @ts-expect-error DSQLSchemaModule restricts schema builders for Aurora DSQL.
+  override withPlugin(plugin: KyselyPlugin): DSQLSchemaModule {
+    // SAFETY: The subclass changes types only and adds no runtime state.
+    return super.withPlugin(plugin) as DSQLSchemaModule;
+  }
+
+  /**
+   * Removes all plugins and keeps the restricted schema module.
+   *
+   * @returns A restricted schema module without plugins.
+   * @example
+   * ```ts
+   * const schema = db.schema.withoutPlugins();
+   * ```
+   */
+  // @ts-expect-error DSQLSchemaModule restricts schema builders for Aurora DSQL.
+  override withoutPlugins(): DSQLSchemaModule {
+    // SAFETY: The subclass changes types only and adds no runtime state.
+    return super.withoutPlugins() as DSQLSchemaModule;
+  }
+
+  /**
+   * Selects a schema and keeps the restricted schema module.
+   *
+   * @param schema - The schema name.
+   * @returns A restricted schema module for the schema.
+   * @example
+   * ```ts
+   * const schema = db.schema.withSchema("public");
+   * ```
+   */
+  // @ts-expect-error DSQLSchemaModule restricts schema builders for Aurora DSQL.
+  override withSchema(schema: string): DSQLSchemaModule {
+    // SAFETY: The subclass changes types only and adds no runtime state.
+    return super.withSchema(schema) as DSQLSchemaModule;
+  }
+
+  /**
+   * Creates a restricted builder for a new table.
+   *
+   * @param table - The table name.
+   * @returns A builder that accepts Aurora DSQL column types.
+   * @example
+   * ```ts
+   * db.schema.createTable("person").addColumn("id", "uuid");
+   * ```
+   */
+  override createTable<TB extends string>(
+    table: TB
+  ): DSQLCreateTableBuilder<TB, never> {
+    // SAFETY: The subclass changes types only and adds no runtime state.
+    return super.createTable(table) as DSQLCreateTableBuilder<TB, never>;
+  }
+
+  /**
+   * Creates a restricted builder for a table alteration.
+   *
+   * @param table - The table name.
+   * @returns A builder that accepts Aurora DSQL types for new columns.
+   * @example
+   * ```ts
+   * db.schema.alterTable("person").addColumn("name", "text");
+   * ```
+   */
+  override alterTable(table: string): DSQLAlterTableBuilder {
+    // SAFETY: The subclass changes types only and adds no runtime state.
+    return super.alterTable(table) as DSQLAlterTableBuilder;
+  }
+
+  /**
+   * Creates a restricted builder for a new index.
+   *
+   * @param indexName - The index name.
+   * @returns A restricted index builder.
+   * @example
+   * ```ts
+   * db.schema.createIndex("person_email_idx").on("person").column("email");
+   * ```
+   */
+  // @ts-expect-error DSQLSchemaModule restricts the CreateIndexBuilder surface for Aurora DSQL.
+  override createIndex(indexName: string): DSQLCreateIndexBuilder<never> {
+    // SAFETY: The subclass changes types only and adds no runtime state.
+    return super.createIndex(indexName) as DSQLCreateIndexBuilder<never>;
+  }
+
+  /**
+   * Creates a restricted builder for a new view.
+   *
+   * @param viewName - The view name.
+   * @returns A restricted view builder.
+   * @example
+   * ```ts
+   * db.schema.createView("active_users").as(db.selectFrom("users").selectAll());
+   * ```
+   */
+  override createView(viewName: string): DSQLCreateViewBuilder {
+    // SAFETY: The subclass changes types only and adds no runtime state.
+    return super.createView(viewName) as DSQLCreateViewBuilder;
+  }
+
+  /**
+   * Creates a restricted builder to drop an index.
+   *
+   * @param indexName - The index name.
+   * @returns A restricted drop index builder.
+   * @example
+   * ```ts
+   * db.schema.dropIndex("person_email_idx");
+   * ```
+   */
+  override dropIndex(indexName: string): DSQLDropIndexBuilder {
+    // SAFETY: The subclass changes types only and adds no runtime state.
+    return super.dropIndex(indexName) as DSQLDropIndexBuilder;
+  }
+
+  /**
+   * Creates a restricted builder to drop a table.
+   *
+   * @param table - The table name.
+   * @returns A restricted drop table builder.
+   * @example
+   * ```ts
+   * db.schema.dropTable("person");
+   * ```
+   */
+  override dropTable(table: string): DSQLDropTableBuilder {
+    // SAFETY: The subclass changes types only and adds no runtime state.
+    return super.dropTable(table) as DSQLDropTableBuilder;
+  }
+
+  declare createType: (this: never, ...args: never[]) => never;
+  declare alterType: (this: never, ...args: never[]) => never;
+  declare dropType: (this: never, ...args: never[]) => never;
+  declare refreshMaterializedView: (this: never, ...args: never[]) => never;
+}

package/template/vendor/kysely-dsql/dsql/types.ts

@@ -0,0 +1,4 @@
+import type { Kysely } from "kysely";
+
+// oxlint-disable-next-line typescript/no-explicit-any
+export type AnyKysely = Kysely<any>;

package/template/vendor/kysely-dsql/generator/create-migration.ts

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { createMigrationFile } from "./migration-file.js";
+
+/**
+ * Supplies the runtime services for the migration command.
+ *
+ * @example
+ * ```ts
+ * const runtime: CreateMigrationRuntime = {
+ *   argv: ["node", "create-migration.js", "add-person-status"],
+ *   cwd: () => process.cwd(),
+ *   error: console.error,
+ *   exitCode: undefined,
+ *   log: console.log,
+ * };
+ * ```
+ */
+export interface CreateMigrationRuntime {
+  /** The command-line arguments. */
+  readonly argv: readonly string[];
+  /** Gets the current working directory. */
+  readonly cwd: () => string;
+  /** Writes one error message. */
+  readonly error: (message: string) => void;
+  /** Contains the requested process exit code. */
+  exitCode: number | undefined;
+  /** Writes one success message. */
+  readonly log: (message: string) => void;
+}
+
+const processRuntime: CreateMigrationRuntime = {
+  argv: process.argv,
+  cwd: process.cwd,
+  error: console.error,
+  exitCode: undefined,
+  log: console.log,
+};
+
+const errorMessage = (error: Error): string => error.message;
+
+/**
+ * Creates a typed migration from command-line arguments.
+ *
+ * @param runtime - The command runtime.
+ * @returns A promise that resolves after the command completes.
+ * @example
+ * ```ts
+ * await runCreateMigration({
+ *   argv: ["node", "create-migration.js", "add-person-status"],
+ *   cwd: () => process.cwd(),
+ *   error: console.error,
+ *   exitCode: undefined,
+ *   log: console.log,
+ * });
+ * ```
+ */
+export async function runCreateMigration(
+  runtime: CreateMigrationRuntime
+): Promise<void> {
+  const name = runtime.argv[2]?.trim() ?? "";
+  if (!name) {
+    runtime.error("Migration name is required.");
+    runtime.exitCode = 1;
+    return;
+  }
+
+  try {
+    const filePath = await createMigrationFile({
+      migrationDirectory: path.resolve(runtime.cwd(), "lib/db/migrations"),
+      name,
+    });
+    runtime.log(filePath);
+  } catch (error) {
+    // SAFETY: The validation and Node file operations reject with Error objects.
+    runtime.error(errorMessage(error as Error));
+    runtime.exitCode = 1;
+  }
+}
+
+const [, entryPath] = process.argv;
+if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
+  await runCreateMigration(processRuntime);
+  process.exitCode = processRuntime.exitCode;
+}

package/template/vendor/kysely-dsql/generator/generate-types-from-pglite.ts

@@ -0,0 +1,40 @@
+import path from "node:path";
+import process from "node:process";
+
+import { PGlite } from "@electric-sql/pglite";
+import { PGliteDialect } from "kysely";
+
+import type { Database } from "../../../lib/db/db";
+import { DSQLKysely } from "../dsql/dsql-kysely";
+import plugins from "../plugins";
+import { writeGeneratedTypes } from "./generated-types-writer.js";
+import { generateTypes } from "./type-generator.js";
+
+const DEFAULT_OUTPUT_DIRECTORY = "lib/db";
+
+const db: DSQLKysely<Database> = new DSQLKysely<Database>({
+  dialect: new PGliteDialect({
+    pglite: new PGlite("./.pglite_development"),
+  }),
+  plugins,
+});
+
+const createDatabaseTypes = async (outputDirectory: string): Promise<void> => {
+  try {
+    const types = await generateTypes(db);
+    await writeGeneratedTypes(outputDirectory, types);
+    console.log(`Database types written to ${outputDirectory}`);
+  } finally {
+    await db.destroy();
+  }
+};
+
+const main = async (): Promise<void> => {
+  const outputDirectory = path.resolve(
+    process.argv[2] ?? DEFAULT_OUTPUT_DIRECTORY
+  );
+  await createDatabaseTypes(outputDirectory);
+};
+if (!["production", "test"].includes(process.env.NODE_ENV ?? "")) {
+  await main();
+}

package/template/vendor/kysely-dsql/generator/generated-types-writer.ts

@@ -0,0 +1,73 @@
+import type { Dirent } from "node:fs";
+import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { GeneratedDatabaseTypes } from "./type-generator.js";
+import { GENERATED_FILE_HEADER } from "./type-generator.js";
+
+const writeTableFiles = async (
+  tableDirectory: string,
+  tableSources: ReadonlyMap<string, string>
+): Promise<void> => {
+  await Promise.all(
+    [...tableSources].map(([fileName, source]) =>
+      writeFile(path.join(tableDirectory, fileName), source, "utf-8")
+    )
+  );
+};
+
+const removeStaleTableFile = async (
+  tableDirectory: string,
+  expectedFiles: ReadonlySet<string>,
+  entry: Dirent
+): Promise<void> => {
+  const isStaleTypeFile =
+    entry.isFile() &&
+    entry.name.endsWith(".ts") &&
+    !expectedFiles.has(entry.name);
+  if (!isStaleTypeFile) {
+    return;
+  }
+
+  const filePath = path.join(tableDirectory, entry.name);
+  const source = await readFile(filePath, "utf-8");
+  if (source.startsWith(GENERATED_FILE_HEADER)) {
+    await unlink(filePath);
+  }
+};
+
+const removeStaleTableFiles = async (
+  tableDirectory: string,
+  expectedFiles: ReadonlySet<string>
+): Promise<void> => {
+  const entries = await readdir(tableDirectory, { withFileTypes: true });
+  await Promise.all(
+    entries.map((entry) => {
+      return removeStaleTableFile(tableDirectory, expectedFiles, entry);
+    })
+  );
+};
+
+/**
+ * Write the database types and remove table files for dropped tables.
+ *
+ * @param outputDirectory - The directory that contains `db.ts`.
+ * @param types - The generated database types.
+ */
+export async function writeGeneratedTypes(
+  outputDirectory: string,
+  types: GeneratedDatabaseTypes
+): Promise<void> {
+  const tableDirectory = path.join(outputDirectory, "tables");
+  await mkdir(tableDirectory, { recursive: true });
+  await writeFile(
+    path.join(outputDirectory, "db.ts"),
+    types.databaseSource,
+    "utf-8"
+  );
+  await writeTableFiles(tableDirectory, types.tableSources);
+  await removeStaleTableFiles(
+    tableDirectory,
+    new Set(types.tableSources.keys())
+  );
+}

package/template/vendor/kysely-dsql/generator/migration-file.ts

@@ -0,0 +1,73 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const MIGRATION_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+
+const migrationSource = `// oxlint-disable typescript/no-explicit-any
+import type { DSQLKysely } from "../../../vendor/kysely-dsql/dsql/dsql-kysely";
+
+export async function up(db: DSQLKysely<any>): Promise<void> {
+  // Add the forward schema change.
+}
+
+export async function down(db: DSQLKysely<any>): Promise<void> {
+  // Add the reverse schema change.
+}
+`;
+
+/**
+ * Supplies the inputs for one migration file.
+ *
+ * @example
+ * ```ts
+ * const options: CreateMigrationFileOptions = {
+ *   migrationDirectory: "migrations",
+ *   name: "add-person-status",
+ *   timestamp: 1_787_403_659_643,
+ * };
+ * ```
+ */
+export interface CreateMigrationFileOptions {
+  /** The directory for the migration file. */
+  readonly migrationDirectory: string;
+  /** The lowercase hyphen-case migration name. */
+  readonly name: string;
+  /** The optional millisecond timestamp. */
+  readonly timestamp?: number;
+}
+
+/**
+ * Creates one typed migration file without replacement.
+ *
+ * @param options - The migration file options.
+ * @returns The absolute path of the new migration file.
+ * @throws {Error} If the name is invalid or the file cannot be created.
+ * @example
+ * ```ts
+ * const filePath = await createMigrationFile({
+ *   migrationDirectory: "migrations",
+ *   name: "add-person-status",
+ * });
+ * ```
+ */
+export async function createMigrationFile(
+  options: CreateMigrationFileOptions,
+): Promise<string> {
+  if (!MIGRATION_NAME_PATTERN.test(options.name)) {
+    throw new Error(
+      "Migration name must use lowercase letters, digits, and single hyphens.",
+    );
+  }
+
+  const timestamp = options.timestamp ?? Date.now();
+  const migrationDirectory = path.resolve(options.migrationDirectory);
+  const filePath = path.join(
+    migrationDirectory,
+    `${timestamp}_${options.name}.ts`,
+  );
+
+  await mkdir(migrationDirectory, { recursive: true });
+  await writeFile(filePath, migrationSource, { encoding: "utf-8", flag: "wx" });
+
+  return filePath;
+}