@kensio/yulin 0.0.1

package/src/service/dynamodb/dynamodb-table.iso.test.ts

@@ -0,0 +1,41 @@
+import { describe, it } from "vitest";
+import { CreateTableCommand } from "@aws-sdk/client-dynamodb";
+import { SimDynamoDbTable } from "./dynamodb-table.js";
+import {
+  assertIdentical,
+  assertInstanceOf,
+  assertThrowsError,
+} from "@kensio/smartass";
+
+describe("SimDynamoDbTable", () => {
+  it("throws when TableName is undefined", () => {
+    const command = new CreateTableCommand({ TableName: undefined });
+
+    assertThrowsError(() => new SimDynamoDbTable(command));
+  });
+
+  it("creates table with CREATING status", () => {
+    const command = new CreateTableCommand({
+      TableName: "test-table",
+    });
+
+    const table = new SimDynamoDbTable(command);
+
+    assertIdentical(table.tableName, "test-table");
+    assertIdentical(table.status, "CREATING");
+    assertInstanceOf(table.creationDateTime, Date);
+  });
+
+  it("activates table", async () => {
+    const command = new CreateTableCommand({
+      TableName: "test-table",
+    });
+
+    const table = new SimDynamoDbTable(command);
+    assertIdentical(table.status, "CREATING");
+
+    await table.activate();
+
+    assertIdentical(table.status, "ACTIVE");
+  });
+});

package/src/service/dynamodb/dynamodb-table.ts

@@ -0,0 +1,46 @@
+import type { Brand } from "../../util/brand.type.js";
+import type { CreateTableCommand, TableStatus } from "@aws-sdk/client-dynamodb";
+
+export type DynamoDbTableName = Brand<string, "DynamoDbTableName">;
+
+/**
+ * Simulated DynamoDB Table.
+ */
+export class SimDynamoDbTable {
+  public readonly creationDateTime: Date;
+
+  private readonly _tableName: DynamoDbTableName;
+  private _status: TableStatus = "CREATING";
+
+  constructor(private readonly createCommand: CreateTableCommand) {
+    if (createCommand.input.TableName === undefined) {
+      throw new Error(
+        "DynamoDB CreateTableCommand.input.TableName is required",
+      );
+    }
+    this._tableName = this.createCommand.input.TableName as DynamoDbTableName;
+    this.creationDateTime = new Date();
+  }
+
+  /**
+   * Simulate the table entering ACTIVE status.
+   */
+  activate(): Promise<void> {
+    this._status = "ACTIVE";
+    return Promise.resolve();
+  }
+
+  /**
+   * Get the DynamoDB table name.
+   */
+  public get tableName(): DynamoDbTableName {
+    return this._tableName;
+  }
+
+  /**
+   * Get the current table status.
+   */
+  public get status(): TableStatus {
+    return this._status;
+  }
+}

package/src/service/dynamodb/dynamodb.ts

@@ -0,0 +1,46 @@
+import type {
+  CreateTableCommand,
+  CreateTableOutput,
+  DescribeTableCommand,
+  DescribeTableOutput,
+  ListTablesCommand,
+  ListTablesOutput,
+} from "@aws-sdk/client-dynamodb";
+import type { DynamoDbTableName, SimDynamoDbTable } from "./dynamodb-table.js";
+import { CreateTableCommandHandler } from "./command/create-table/create-table.handler.js";
+import type { BackgroundScheduler } from "../../util/background/background.js";
+import { ListTablesCommandHandler } from "./command/list-tables/list-tables.handler.js";
+import { DescribeTableCommandHandler } from "./command/describe-table/describe-table.handler.js";
+
+/**
+ * Simulated DynamoDB. Handles SDK commands. Emulates AWS behaviour and state.
+ */
+export class SimDynamoDb {
+  private readonly tables = new Map<DynamoDbTableName, SimDynamoDbTable>();
+
+  constructor(private readonly background: BackgroundScheduler) {}
+
+  /**
+   * Handle a Create Table Command from the SDK.
+   */
+  async createTable(cmd: CreateTableCommand): Promise<CreateTableOutput> {
+    const handler = new CreateTableCommandHandler(this.tables, this.background);
+    return await handler.handle(cmd);
+  }
+
+  /**
+   * Handle a List Tables Command from the SDK.
+   */
+  async listTables(cmd: ListTablesCommand): Promise<ListTablesOutput> {
+    const handler = new ListTablesCommandHandler(this.tables);
+    return await handler.handle(cmd);
+  }
+
+  /**
+   * Handle a Describe Table Command from the SDK.
+   */
+  async describeTable(cmd: DescribeTableCommand): Promise<DescribeTableOutput> {
+    const handler = new DescribeTableCommandHandler(this.tables);
+    return await handler.handle(cmd);
+  }
+}

package/src/service/organizations/sim-aws-account.ts

@@ -0,0 +1,36 @@
+import {
+  type BackgroundCompleter,
+  type BackgroundScheduler,
+  BackgroundTasks,
+} from "../../util/background/background.js";
+import { SimDynamoDb } from "../dynamodb/dynamodb.js";
+import { Memo } from "../../util/memo/memo.js";
+
+/**
+ * Container for simulated AWS services.
+ */
+export class SimAwsAccount {
+  private readonly memo = new Memo<object>();
+
+  constructor(
+    private readonly background: BackgroundScheduler &
+      BackgroundCompleter = new BackgroundTasks(),
+  ) {}
+
+  /**
+   * Wait for all outstanding background tasks in this Account to complete.
+   */
+  async backgroundTasksComplete(): Promise<void> {
+    await this.background.complete();
+  }
+
+  /**
+   * Get the simulated DynamoDB service in this simulated Account.
+   */
+  getDynamoDb(): SimDynamoDb {
+    return this.memo.getOrCreate(
+      "DynamoDB",
+      () => new SimDynamoDb(this.background),
+    );
+  }
+}

package/src/util/background/background.iso.test.ts

@@ -0,0 +1,74 @@
+import { describe, it } from "vitest";
+import { BackgroundTasks } from "./background.js";
+import {
+  assertFalse,
+  assertIdentical,
+  assertThrowsErrorAsync,
+  assertTrue,
+} from "@kensio/smartass";
+
+describe("BackgroundTasks", () => {
+  it("executes scheduled tasks", async () => {
+    const tasks = new BackgroundTasks();
+    let executed = false;
+
+    tasks.schedule(async () => {
+      await Promise.resolve();
+      executed = true;
+    });
+
+    assertFalse(executed);
+    await tasks.complete();
+    assertTrue(executed);
+  });
+
+  it("tracks pending task count", async () => {
+    const tasks = new BackgroundTasks();
+
+    assertIdentical(tasks.size, 0);
+
+    tasks.schedule(async () => {
+      /* empty */
+    });
+    tasks.schedule(async () => {
+      /* empty */
+    });
+    tasks.schedule(async () => {
+      /* empty */
+    });
+
+    assertIdentical(tasks.size, 3);
+    await tasks.complete();
+    assertIdentical(tasks.size, 0);
+  });
+
+  it("handles tasks that schedule more tasks", async () => {
+    const tasks = new BackgroundTasks();
+    const execOrder: number[] = [];
+
+    tasks.schedule(async () => {
+      await Promise.resolve();
+      execOrder.push(1);
+      tasks.schedule(async () => {
+        await Promise.resolve();
+        execOrder.push(2);
+      });
+    });
+
+    await tasks.complete();
+    assertIdentical(execOrder.length, 2);
+    assertIdentical(execOrder[0], 1);
+    assertIdentical(execOrder[1], 2);
+  });
+
+  it("propagates task errors", async () => {
+    const tasks = new BackgroundTasks();
+
+    tasks.schedule(async () => {
+      await Promise.resolve();
+      throw new Error("Task failed");
+    });
+
+    await assertThrowsErrorAsync(async () => tasks.complete());
+  });
+});

package/src/util/background/background.ts

@@ -0,0 +1,62 @@
+export type BackgroundTask = () => Promise<void>;
+
+export interface BackgroundScheduler {
+  schedule(task: BackgroundTask): void;
+}
+
+export interface BackgroundCompleter {
+  complete(): Promise<void>;
+}
+
+/**
+ * Simple async background tasks scheduler, to simulate asynchronous distributed
+ * operations occurring in a non-deterministic sequence.
+ */
+export class BackgroundTasks
+  implements BackgroundScheduler, BackgroundCompleter
+{
+  private readonly pending = new Set<Promise<void>>();
+
+  /**
+   * Schedule a task to happen asynchronously in the background.
+   */
+  schedule(task: BackgroundTask): void {
+    const promise = new Promise<void>((resolve) => {
+      setTimeout(resolve, Math.random() * 3);
+    })
+      .then(task)
+      .then(
+        () => {
+          //
+        },
+        (error: unknown) => {
+          // Keep the promise rejected so drain() can surface failures
+          // deterministically.
+          throw error;
+        },
+      )
+      .finally(() => {
+        this.pending.delete(promise);
+      });
+
+    this.pending.add(promise);
+  }
+
+  /**
+   * Wait until all tasks currently scheduled have finished.
+   * If tasks schedule more tasks, this will continue draining until idle.
+   */
+  public async complete(): Promise<void> {
+    while (this.pending.size > 0) {
+      // eslint-disable-next-line no-await-in-loop
+      await Promise.all(this.pending);
+    }
+  }
+
+  /**
+   * See how many outstanding background tasks are scheduled.
+   */
+  public get size(): number {
+    return this.pending.size;
+  }
+}

package/src/util/brand.type.ts

@@ -0,0 +1,11 @@
+export type Brand<K, T extends string> = K & Record<T, never>;
+
+export type ISODateString = Brand<
+  `${number}-${number}-${number}T${number}:${number}:${number}.${number}Z`,
+  "ISODateString"
+>;
+declare global {
+  interface Date {
+    toISOString(): ISODateString;
+  }
+}

package/src/util/memo/memo.iso.test.ts

@@ -0,0 +1,43 @@
+import { describe, it } from "vitest";
+import { Memo } from "./memo.js";
+import { assertIdentical } from "@kensio/smartass";
+
+describe("Memo", () => {
+  it("creates and caches values", () => {
+    const memo = new Memo<string>();
+    let callCount = 0;
+
+    const value1 = memo.getOrCreate("key1", () => {
+      callCount++;
+      return "value1";
+    });
+    const value2 = memo.getOrCreate("key1", () => {
+      callCount++;
+      return "different";
+    });
+
+    assertIdentical(value1, "value1");
+    assertIdentical(value2, "value1");
+    assertIdentical(callCount, 1);
+  });
+
+  it("handles multiple keys independently", () => {
+    const memo = new Memo<number>();
+
+    const a = memo.getOrCreate("a", () => 10);
+    const b = memo.getOrCreate("b", () => 20);
+    const c = memo.getOrCreate("a", () => 99);
+
+    assertIdentical(a, 10);
+    assertIdentical(b, 20);
+    assertIdentical(c, 10);
+  });
+
+  it("checks key existence", () => {
+    const memo = new Memo<string>();
+
+    assertIdentical(memo.has("key"), false);
+    memo.getOrCreate("key", () => "value");
+    assertIdentical(memo.has("key"), true);
+  });
+});

package/src/util/memo/memo.ts

@@ -0,0 +1,26 @@
+/**
+ * Simple memoization cache.
+ */
+export class Memo<T> {
+  private readonly cache = new Map<PropertyKey, T>();
+
+  /**
+   * Returns the cached value for the given key, or creates/caches it using `factory`.
+   */
+  getOrCreate<V extends T>(key: PropertyKey, factory: () => V): V {
+    if (this.cache.has(key)) {
+      return this.cache.get(key) as V;
+    }
+
+    const value = factory();
+    this.cache.set(key, value);
+    return value;
+  }
+
+  /**
+   * Returns whether the cache contains `key`.
+   */
+  has(key: PropertyKey): boolean {
+    return this.cache.has(key);
+  }
+}

package/src/util/sleep.ts

@@ -0,0 +1,16 @@
+/**
+ * Async sleep for an approximate number of milliseconds.
+ */
+export async function sleep(ms = 0): Promise<void> {
+  await new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Sleep for a random but short length of time, e.g. to simulate asynchronous
+ * operations completing in a non-deterministic order.
+ */
+export async function jitter(): Promise<void> {
+  await sleep(Math.random() * 2);
+}

package/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noEmitOnError": true
+  },
+  "include": ["src/**/*", "typings/**/*.d.ts"],
+  "exclude": ["**/*.test.*", "**/*.spec.*", "test/**/*"]
+}

package/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "types": ["node"],
+
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowUnusedLabels": false,
+    "allowUnreachableCode": false,
+
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": false,
+
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": ["src/**/*", "test/**/*", "typings/**/*.d.ts"]
+}

package/typings/eslint-plugin-promise.d.ts

@@ -0,0 +1,11 @@
+declare module "eslint-plugin-promise" {
+  import type { ESLint } from "eslint";
+
+  const plugin: ESLint.Plugin & {
+    configs: {
+      "flat/recommended": ESLint.Plugin;
+    };
+  };
+
+  export default plugin;
+}

package/vitest.config.ts

@@ -0,0 +1,50 @@
+import { fileURLToPath } from "node:url";
+import { configDefaults, defineConfig } from "vitest/config";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "#test": fileURLToPath(new URL("./test", import.meta.url)),
+    },
+  },
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+    typecheck: {
+      tsconfig: "./tsconfig.json",
+    },
+    coverage: {
+      provider: "v8",
+      include: ["src/**/*.ts"],
+      exclude: [...configDefaults.exclude],
+      reporter: ["text", "lcov"],
+      reportsDirectory: "./test/.coverage",
+      thresholds: {
+        statements: 90,
+        branches: 90,
+        functions: 90,
+        lines: 90,
+      },
+    },
+    restoreMocks: true,
+    testTimeout: 10_000,
+    projects: [
+      {
+        extends: true,
+        test: {
+          name: "isolatedTests",
+          include: ["src/**/*.iso.test.ts"],
+          // globalSetup: ["./test/isoTestGlobalSetUp.ts"],
+        },
+      },
+      {
+        extends: true,
+        test: {
+          name: "localTests",
+          include: ["src/**/*.loc.test.ts"],
+          // globalSetup: ["./test/locTestGlobalSetUp.ts"],
+        },
+      },
+    ],
+  },
+});