@kensio/yulin 0.0.1

package/eslint.config.ts

@@ -0,0 +1,208 @@
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import eslint from "@eslint/js";
+import vitest from "@vitest/eslint-plugin";
+import { defineConfig } from "eslint/config";
+import prettier from "eslint-config-prettier";
+import { jsdoc } from "eslint-plugin-jsdoc";
+import noSecrets from "eslint-plugin-no-secrets";
+import security from "eslint-plugin-security";
+import unicorn from "eslint-plugin-unicorn";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig(
+  // ── Global ignores ──────────────────────────────────────
+  {
+    ignores: ["dist/", "**/.coverage/*", "node_modules/", "*.config.ts"],
+  },
+
+  // ── Base ESLint recommended ─────────────────────────────
+  eslint.configs.recommended,
+
+  // ── TypeScript (strictest level + type-aware) ───────────
+  ...tseslint.configs.strictTypeChecked,
+  ...tseslint.configs.stylisticTypeChecked,
+
+  // ── General settings for all TS files ───────────────────
+  {
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.node,
+      },
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: __dirname,
+      },
+    },
+    rules: {
+      // ── TypeScript overrides & additions ──────────────
+      "@typescript-eslint/explicit-function-return-type": "error",
+      "@typescript-eslint/explicit-module-boundary-types": "error",
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/consistent-type-imports": [
+        "error",
+        { prefer: "type-imports", fixStyle: "inline-type-imports" },
+      ],
+      "@typescript-eslint/consistent-type-exports": [
+        "error",
+        { fixMixedExportsWithInlineTypeSpecifier: true },
+      ],
+      "@typescript-eslint/no-import-type-side-effects": "error",
+      "@typescript-eslint/switch-exhaustiveness-check": "error",
+      "@typescript-eslint/no-unnecessary-condition": "error",
+      "@typescript-eslint/prefer-nullish-coalescing": "error",
+      "@typescript-eslint/strict-boolean-expressions": "error",
+      "no-await-in-loop": "error", // catches sequential awaits that should be Promise.all()
+      "no-template-curly-in-string": "error", // catches '${name}' in regular strings (missing backticks)
+      "no-promise-executor-return": "error", // catches accidental return in new Promise((resolve) => return ...)
+      "no-unreachable-loop": "error", // catches loops that only ever run once
+      "no-param-reassign": "error", // prevents mutating function parameters (major bug source)
+      "prefer-const": "error", // const over let when never reassigned
+      "object-shorthand": ["error", "always"], // { foo: foo } → { foo }
+      "prefer-template": "error", // template literals over string concatenation
+      "@typescript-eslint/prefer-readonly": "error", // flags private fields that are never reassigned
+      "@typescript-eslint/require-array-sort-compare": "error", // prevents [1, 10, 2].sort() (lexicographic surprise)
+      "@typescript-eslint/naming-convention": [
+        "error",
+        {
+          selector: ["property", "objectLiteralProperty", "typeProperty"],
+          format: ["camelCase", "PascalCase"],
+          leadingUnderscore: "allow",
+        },
+        {
+          selector: "default",
+          format: ["camelCase"],
+          leadingUnderscore: "allow",
+        },
+        {
+          selector: "typeLike",
+          format: ["PascalCase"],
+        },
+        {
+          selector: "enumMember",
+          format: ["PascalCase"],
+        },
+        {
+          selector: "variable",
+          modifiers: ["const", "exported"],
+          format: ["camelCase", "UPPER_CASE"],
+        },
+      ],
+
+      // ── General quality ──────────────────────────────
+      "no-console": "warn",
+      eqeqeq: ["error", "always"],
+      curly: ["error", "all"],
+      "@typescript-eslint/only-throw-error": "error",
+    },
+  },
+
+  // ── Security (low cost security checks) ────────────────
+  // TODO: Remove cast when eslint-plugin-security fixes defineConfig() types
+  // https://github.com/eslint-community/eslint-plugin-security/issues/175
+  security.configs.recommended as any,
+
+  // ── Unicorn (modern JS best practices) ──────────────────
+  // https://github.com/sindresorhus/eslint-plugin-unicorn?tab=readme-ov-file#recommended-config
+  unicorn.configs.recommended,
+  {
+    rules: {
+      "unicorn/better-regex": "warn",
+      "unicorn/prevent-abbreviations": "off",
+    },
+  },
+
+  // ── Vitest (test files only) ────────────────────────────
+  {
+    files: ["**/*.test.ts"],
+    plugins: {
+      vitest,
+    },
+    rules: {
+      ...vitest.configs.recommended.rules,
+      "vitest/consistent-test-it": ["error", { fn: "it" }],
+      "vitest/no-focused-tests": "error",
+      "vitest/no-disabled-tests": "warn",
+      "vitest/no-duplicate-hooks": "error",
+      "vitest/prefer-to-be": "error",
+      "vitest/prefer-to-have-length": "error",
+      "vitest/prefer-strict-equal": "error",
+      "vitest/require-top-level-describe": "error",
+      "vitest/expect-expect": "off",
+
+      // Relax some rules that are too strict for test files
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-unsafe-assignment": "off",
+      "@typescript-eslint/no-unsafe-member-access": "off",
+      "@typescript-eslint/explicit-function-return-type": "off",
+      "import-x/no-default-export": "off",
+    },
+  },
+
+  // ── Config files (allow default exports) ────────────────
+  {
+    files: ["*.config.ts", "*.config.js"],
+    rules: {
+      "import-x/no-default-export": "off",
+    },
+  },
+
+  // ── No Secrets (detect accidental secret inclusion) ────────
+  {
+    plugins: { "no-secrets": noSecrets },
+    rules: {
+      "no-secrets/no-secrets": "error",
+    },
+  },
+
+  // ── JSDoc (enforce minimal doc commenting) ────────────────
+  jsdoc({
+    config: "flat/recommended-error",
+  }),
+  {
+    rules: {
+      "jsdoc/require-param": "off",
+      "jsdoc/require-returns": "off",
+      "jsdoc/require-param-description": "off",
+      "jsdoc/require-returns-description": "off",
+      "jsdoc/require-yields": "off",
+      "jsdoc/require-description": [
+        "error",
+        {
+          descriptionStyle: "body",
+          checkConstructors: false,
+          checkGetters: false,
+          checkSetters: false,
+        },
+      ],
+      "jsdoc/require-jsdoc": [
+        "error",
+        {
+          contexts: [
+            "ClassDeclaration",
+            "ExportNamedDeclaration > VariableDeclaration[kind='const'] > VariableDeclarator[init.type='ObjectExpression']",
+            "ExportNamedDeclaration > VariableDeclaration[kind='const'] > VariableDeclarator[init.type='ArrayExpression']",
+            "ExportNamedDeclaration > VariableDeclaration[kind='const'] > VariableDeclarator[init.type='NewExpression']",
+            "ExportNamedDeclaration > VariableDeclaration[kind='const'] > VariableDeclarator[init.type='CallExpression']",
+          ],
+          publicOnly: true,
+          checkConstructors: false,
+          require: {
+            FunctionDeclaration: true,
+            MethodDefinition: true,
+            ClassDeclaration: true,
+          },
+        },
+      ],
+    },
+  },
+
+  // ── Prettier (must be last — disables conflicting rules)
+  prettier,
+);

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@kensio/yulin",
+  "version": "0.0.1",
+  "description": "AWS system behaviour simulation for isolated unit testing",
+  "repository": "https://github.com/KensioSoftware/yulin",
+  "type": "module",
+  "main": "index.js",
+  "keywords": [
+    "aws",
+    "test",
+    "mock",
+    "emulator",
+    "simulator",
+    "isolated"
+  ],
+  "author": "Kensio Software",
+  "license": "AGPL-3.0",
+  "devDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.1001.0",
+    "@aws-sdk/client-s3": "^3.1001.0",
+    "@eslint/js": "^10.0.1",
+    "@kensio/smartass": "^0.1.4",
+    "@smithy/smithy-client": "^4.12.1",
+    "@smithy/types": "^4.13.0",
+    "@types/eslint-plugin-security": "^3.0.1",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "^25.3.0",
+    "@vitest/coverage-v8": "4.0.18",
+    "@vitest/eslint-plugin": "^1.6.9",
+    "aws-sdk-client-mock": "^4.1.0",
+    "eslint": "^10.0.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsdoc": "^62.7.1",
+    "eslint-plugin-no-secrets": "^2.2.2",
+    "eslint-plugin-security": "^4.0.0",
+    "eslint-plugin-unicorn": "^63.0.0",
+    "globals": "^17.3.0",
+    "jiti": "^2.6.1",
+    "prettier": "^3.8.1",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.1001.0",
+    "@aws-sdk/client-s3": "^3.1001.0",
+    "@smithy/smithy-client": "^4.12.1"
+  },
+  "peerDependenciesMeta": {
+    "@smithy/smithy-client": {
+      "optional": true
+    },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/client-dynamodb": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "lodash-es": "^4.17.23"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "fmt": "eslint --fix '{src,test}/**/*.{ts,js}' && prettier --write '{src,test}/**/*.{ts,js,json,md,css,html,yml,yaml}'",
+    "lint": "eslint '{src,test}/**/*.{ts,js}' && prettier --check '{src,test}/**/*.{ts,js,json,md,css,html,yml,yaml}'",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/pnpm-workspace.yaml

@@ -0,0 +1 @@
+useNodeVersion: 24.13.1

package/src/command/command-handler.ts

@@ -0,0 +1,3 @@
+export interface CommandHandler<TCommand, TOutput> {
+  handle(cmd: TCommand): Promise<TOutput>;
+}

package/src/service/dynamodb/command/create-table/create-table.handler.ts

@@ -0,0 +1,59 @@
+import type { DynamoDbTableName } from "../../dynamodb-table.js";
+import { SimDynamoDbTable } from "../../dynamodb-table.js";
+import {
+  type CreateTableCommand,
+  type CreateTableCommandOutput,
+  ResourceInUseException,
+} from "@aws-sdk/client-dynamodb";
+import type { BackgroundScheduler } from "../../../../util/background/background.js";
+import type { CommandHandler } from "../../../../command/command-handler.js";
+import { jitter } from "../../../../util/sleep.js";
+
+/**
+ * DynamoDB CreateTableCommand handler.
+ */
+export class CreateTableCommandHandler implements CommandHandler<
+  CreateTableCommand,
+  CreateTableCommandOutput
+> {
+  constructor(
+    private readonly tables: Map<DynamoDbTableName, SimDynamoDbTable>,
+    private readonly background: BackgroundScheduler,
+  ) {}
+
+  /**
+   * Handle creation of a new DynamoDB Table.
+   */
+  async handle(cmd: CreateTableCommand): Promise<CreateTableCommandOutput> {
+    if (cmd.input.TableName === undefined) {
+      throw new Error("CreateTableCommand.input.TableName is required");
+    }
+
+    const tableName = cmd.input.TableName as DynamoDbTableName;
+    if (this.tables.has(tableName)) {
+      throw new ResourceInUseException({
+        message: `DynamoDB Table ${tableName} already exists`,
+        $metadata: {},
+      });
+    }
+
+    await jitter();
+
+    const table = new SimDynamoDbTable(cmd);
+    this.tables.set(tableName, table);
+
+    this.background.schedule(() => table.activate());
+
+    return {
+      TableDescription: {
+        AttributeDefinitions: [],
+        TableName: tableName,
+        KeySchema: [],
+        TableStatus: table.status,
+        CreationDateTime: table.creationDateTime,
+        GlobalSecondaryIndexes: [],
+      },
+      $metadata: {},
+    };
+  }
+}

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

@@ -0,0 +1,67 @@
+import { describe, it } from "vitest";
+import {
+  CreateTableCommand,
+  ListTablesCommand,
+  ResourceInUseException,
+} from "@aws-sdk/client-dynamodb";
+import { SimAwsAccount } from "../../../organizations/sim-aws-account.js";
+import {
+  assertArrayLength,
+  assertIdentical,
+  assertInstanceOf,
+  assertNonNullable,
+  assertThrowsErrorAsync,
+} from "@kensio/smartass";
+
+describe("DynamoDB CreateTableCommand", () => {
+  it("creates new DynamoDB Table", async () => {
+    const simAccount = new SimAwsAccount();
+    const simDynamoDb = simAccount.getDynamoDb();
+
+    const createTableOutput = await simDynamoDb.createTable(
+      new CreateTableCommand({ TableName: "FoobarTable" }),
+    );
+
+    assertNonNullable(createTableOutput.TableDescription);
+    assertIdentical(
+      createTableOutput.TableDescription.TableName,
+      "FoobarTable",
+    );
+    assertIdentical(createTableOutput.TableDescription.TableStatus, "CREATING");
+
+    const listTablesOutput = await simDynamoDb.listTables(
+      new ListTablesCommand(),
+    );
+
+    assertArrayLength(listTablesOutput.TableNames, 1);
+    assertIdentical(listTablesOutput.TableNames[0], "FoobarTable");
+
+    await simAccount.backgroundTasksComplete();
+  });
+
+  it("throws on undefined Table name", async () => {
+    const simAccount = new SimAwsAccount();
+    const simDynamoDb = simAccount.getDynamoDb();
+
+    await assertThrowsErrorAsync(async () =>
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: undefined })),
+    );
+  });
+
+  it("throws on duplicate Table name", async () => {
+    const simAccount = new SimAwsAccount();
+    const simDynamoDb = simAccount.getDynamoDb();
+
+    await simDynamoDb.createTable(
+      new CreateTableCommand({ TableName: "FoobarTable" }),
+    );
+
+    const error = await assertThrowsErrorAsync(async () =>
+      simDynamoDb.createTable(
+        new CreateTableCommand({ TableName: "FoobarTable" }),
+      ),
+    );
+    assertInstanceOf(error, ResourceInUseException);
+    assertIdentical(error.$fault, "client");
+  });
+});

package/src/service/dynamodb/command/describe-table/describe-table.handler.ts

@@ -0,0 +1,50 @@
+import {
+  ResourceNotFoundException,
+  type DescribeTableCommand,
+  type DescribeTableOutput,
+} from "@aws-sdk/client-dynamodb";
+import type { CommandHandler } from "../../../../command/command-handler.js";
+import type {
+  DynamoDbTableName,
+  SimDynamoDbTable,
+} from "../../dynamodb-table.js";
+import { jitter } from "../../../../util/sleep.js";
+
+/**
+ * DynamoDB DescribeTableCommand handler.
+ */
+export class DescribeTableCommandHandler implements CommandHandler<
+  DescribeTableCommand,
+  DescribeTableOutput
+> {
+  constructor(
+    private readonly tables: Map<DynamoDbTableName, SimDynamoDbTable>,
+  ) {}
+
+  /**
+   * Simulate describing DynamoDB Table.
+   */
+  async handle(cmd: DescribeTableCommand): Promise<DescribeTableOutput> {
+    if (cmd.input.TableName === undefined) {
+      throw new Error("DescribeTableCommand.input.TableName is required");
+    }
+    const tableName = cmd.input.TableName as DynamoDbTableName;
+
+    await jitter();
+
+    const table = this.tables.get(tableName);
+    if (table === undefined) {
+      throw new ResourceNotFoundException({
+        message: `No DynamoDB Table named ${tableName}`,
+        $metadata: {},
+      });
+    }
+
+    return {
+      Table: {
+        TableName: table.tableName,
+        TableStatus: table.status,
+      },
+    };
+  }
+}

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

@@ -0,0 +1,67 @@
+import { describe, it } from "vitest";
+import { SimAwsAccount } from "../../../organizations/sim-aws-account.js";
+import {
+  CreateTableCommand,
+  DescribeTableCommand,
+  ResourceNotFoundException,
+} from "@aws-sdk/client-dynamodb";
+import {
+  assertIdentical,
+  assertInstanceOf,
+  assertNonNullable,
+  assertOneOf,
+  assertThrowsErrorAsync,
+} from "@kensio/smartass";
+
+describe("DynamoDB DescribeTableCommand", () => {
+  it("describes DynamoDB Table", async () => {
+    const simAccount = new SimAwsAccount();
+    const simDynamoDb = simAccount.getDynamoDb();
+
+    await Promise.all([
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableA" })),
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableB" })),
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableC" })),
+    ]);
+
+    const describeTableOutput = await simDynamoDb.describeTable(
+      new DescribeTableCommand({ TableName: "TableB" }),
+    );
+
+    assertNonNullable(describeTableOutput.Table?.TableName);
+    assertIdentical(describeTableOutput.Table.TableName, "TableB");
+    assertNonNullable(describeTableOutput.Table.TableStatus);
+    assertOneOf(describeTableOutput.Table.TableStatus, ["CREATING", "ACTIVE"]);
+
+    await simAccount.backgroundTasksComplete();
+
+    const describeAgain = await simDynamoDb.describeTable(
+      new DescribeTableCommand({ TableName: "TableB" }),
+    );
+    assertNonNullable(describeAgain.Table?.TableStatus);
+    assertIdentical(describeAgain.Table.TableStatus, "ACTIVE");
+  });
+
+  it("throws on undefined Table name", async () => {
+    const simAccount = new SimAwsAccount();
+    const simDynamoDb = simAccount.getDynamoDb();
+
+    await assertThrowsErrorAsync(async () =>
+      simDynamoDb.describeTable(
+        new DescribeTableCommand({ TableName: undefined }),
+      ),
+    );
+  });
+
+  it("throws on describing non-existent DynamoDB Table", async () => {
+    const simAccount = new SimAwsAccount();
+    const simDynamoDb = simAccount.getDynamoDb();
+
+    const error = await assertThrowsErrorAsync(async () =>
+      simDynamoDb.describeTable(
+        new DescribeTableCommand({ TableName: "NonExistentTable" }),
+      ),
+    );
+    assertInstanceOf(error, ResourceNotFoundException);
+  });
+});

package/src/service/dynamodb/command/list-tables/list-tables.handler.ts

@@ -0,0 +1,51 @@
+import type { CommandHandler } from "../../../../command/command-handler.js";
+import type {
+  ListTablesCommand,
+  ListTablesOutput,
+} from "@aws-sdk/client-dynamodb";
+import type {
+  DynamoDbTableName,
+  SimDynamoDbTable,
+} from "../../dynamodb-table.js";
+import { jitter } from "../../../../util/sleep.js";
+
+/**
+ * Simulated DynamoDB ListTablesCommand handler.
+ */
+export class ListTablesCommandHandler implements CommandHandler<
+  ListTablesCommand,
+  ListTablesOutput
+> {
+  constructor(
+    private readonly tables: Map<DynamoDbTableName, SimDynamoDbTable>,
+  ) {}
+
+  /**
+   * Simulate listing DynamoDB Tables.
+   */
+  async handle(cmd: ListTablesCommand): Promise<ListTablesOutput> {
+    await jitter();
+
+    const tables = [...this.tables.values()];
+    tables.sort((a, b) => a.tableName.localeCompare(b.tableName));
+
+    const exclusiveStartTableName = cmd.input.ExclusiveStartTableName;
+    const limit = cmd.input.Limit ?? 100;
+
+    const startIndex =
+      exclusiveStartTableName === undefined
+        ? 0
+        : Math.max(
+            0,
+            tables.findIndex((t) => t.tableName === exclusiveStartTableName) +
+              1,
+          );
+
+    const page = tables.slice(startIndex, startIndex + limit);
+
+    return {
+      TableNames: page.map((table) => table.tableName),
+      LastEvaluatedTableName: page.at(-1)?.tableName,
+    };
+  }
+}

package/src/service/dynamodb/command/list-tables/list-tables.iso.test.ts

@@ -0,0 +1,74 @@
+import { describe, it } from "vitest";
+import { SimAwsAccount } from "../../../organizations/sim-aws-account.js";
+import {
+  CreateTableCommand,
+  ListTablesCommand,
+} from "@aws-sdk/client-dynamodb";
+import { assertArrayLength, assertIdentical } from "@kensio/smartass";
+
+describe("DynamoDB ListTablesCommand", () => {
+  it("List all DynamoDB Tables", async () => {
+    const simAccount = new SimAwsAccount();
+    const simDynamoDb = simAccount.getDynamoDb();
+
+    await Promise.all([
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableA" })),
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableB" })),
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableC" })),
+    ]);
+
+    const listTablesOutput = await simDynamoDb.listTables(
+      new ListTablesCommand(),
+    );
+
+    assertArrayLength(listTablesOutput.TableNames, 3);
+
+    assertIdentical(listTablesOutput.TableNames[0], "TableA");
+    assertIdentical(listTablesOutput.TableNames[1], "TableB");
+    assertIdentical(listTablesOutput.TableNames[2], "TableC");
+
+    assertIdentical(listTablesOutput.LastEvaluatedTableName, "TableC");
+  });
+
+  it("List DynamoDB Tables with limit", async () => {
+    const simAccount = new SimAwsAccount();
+    const simDynamoDb = simAccount.getDynamoDb();
+
+    await Promise.all([
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableA" })),
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableB" })),
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableC" })),
+    ]);
+
+    const listTablesOutput = await simDynamoDb.listTables(
+      new ListTablesCommand({ Limit: 2 }),
+    );
+
+    assertArrayLength(listTablesOutput.TableNames, 2);
+
+    assertIdentical(listTablesOutput.TableNames[0], "TableA");
+    assertIdentical(listTablesOutput.TableNames[1], "TableB");
+
+    assertIdentical(listTablesOutput.LastEvaluatedTableName, "TableB");
+  });
+
+  it("List DynamoDB Tables with exclusive start and limit", async () => {
+    const simAccount = new SimAwsAccount();
+    const simDynamoDb = simAccount.getDynamoDb();
+
+    await Promise.all([
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableA" })),
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableB" })),
+      simDynamoDb.createTable(new CreateTableCommand({ TableName: "TableC" })),
+    ]);
+
+    const listTablesOutput = await simDynamoDb.listTables(
+      new ListTablesCommand({ ExclusiveStartTableName: "TableB", Limit: 2 }),
+    );
+
+    assertArrayLength(listTablesOutput.TableNames, 1);
+
+    assertIdentical(listTablesOutput.TableNames[0], "TableC");
+    assertIdentical(listTablesOutput.LastEvaluatedTableName, "TableC");
+  });
+});