local-web-services-javascript-sdk 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,132 @@
+# local-web-services-javascript-sdk
+
+JavaScript testing SDK for [local-web-services](https://github.com/local-web-services/local-web-services) — spawns `ldk dev` in a subprocess and provides pre-configured AWS SDK v3 clients for testing.
+
+## Prerequisites
+
+Install `local-web-services`:
+
+```bash
+pip install local-web-services
+```
+
+## Installation
+
+```bash
+npm install local-web-services-javascript-sdk
+# or
+pnpm add local-web-services-javascript-sdk
+```
+
+## Quick start
+
+```js
+const { LwsSession } = require('local-web-services-javascript-sdk');
+
+// Auto-discover from a CDK project (runs ldk dev against cdk.out/)
+const session = await LwsSession.fromCdk('../my-cdk-project');
+
+// Auto-discover from a Terraform project
+const session = await LwsSession.fromHcl('../my-terraform-project');
+
+// Explicit resource declaration
+const session = await LwsSession.create({
+  tables: [{ name: 'Orders', partitionKey: 'id' }],
+  queues: ['OrderQueue'],
+  buckets: ['ReceiptsBucket'],
+});
+
+// Get a fully-configured AWS SDK v3 client
+const dynamodb = session.client('dynamodb');
+
+// Use the helper API
+const table = session.dynamodb('Orders');
+await table.put({ id: { S: '1' }, status: { S: 'pending' } });
+const items = await table.scan();
+console.log(items.length); // 1
+
+// Always close the session when done
+await session.close();
+```
+
+## Jest example
+
+```js
+// jest.config.js
+module.exports = {
+  testEnvironment: 'node',
+  testTimeout: 60000,   // ldk dev needs time to start
+};
+
+// orders.test.js
+const { LwsSession } = require('local-web-services-javascript-sdk');
+
+let session;
+
+beforeAll(async () => {
+  session = await LwsSession.create({
+    tables: [{ name: 'Orders', partitionKey: 'id' }],
+  });
+});
+
+afterAll(async () => {
+  await session.close();
+});
+
+beforeEach(async () => {
+  await session.reset();
+});
+
+test('creates an order', async () => {
+  const table = session.dynamodb('Orders');
+  await table.put({ id: { S: '42' }, status: { S: 'pending' } });
+
+  const item = await table.assertItemExists({ id: { S: '42' } });
+  expect(item.status.S).toBe('pending');
+});
+```
+
+## Drop-in AWS endpoint redirection
+
+When a session starts, `AWS_ENDPOINT_URL_*` environment variables are automatically set for all supported services. Any AWS SDK v3 client created after the session starts — including clients in your production code — will hit the local LWS services without any code changes:
+
+```js
+// production code
+const { DynamoDBClient } = require('@aws-sdk/client-dynamodb');
+const client = new DynamoDBClient({}); // picks up AWS_ENDPOINT_URL_DYNAMODB automatically
+
+// test code — no endpoint configuration needed
+const session = await LwsSession.create({ tables: [{ name: 'Orders', partitionKey: 'id' }] });
+// production client now talks to LWS
+```
+
+Env vars are restored when `session.close()` is called.
+
+## API
+
+### `LwsSession`
+
+| Method | Description |
+|--------|-------------|
+| `LwsSession.create(spec)` | Start with explicit resource spec |
+| `LwsSession.fromCdk(projectDir)` | Auto-discover from CDK cloud assembly |
+| `LwsSession.fromHcl(projectDir)` | Auto-discover from Terraform `.tf` files |
+| `session.client(service)` | Get AWS SDK v3 client |
+| `session.dynamodb(tableName)` | Get `DynamoDBHelper` |
+| `session.sqs(queueName)` | Get `SQSHelper` |
+| `session.s3(bucketName)` | Get `S3Helper` |
+| `session.reset()` | Clear all state (use in `beforeEach`) |
+| `session.close()` | Stop `ldk dev` process |
+| `session.queueUrl(queueName)` | Get local SQS queue URL |
+| `session.portFor(service)` | Get port number for a service |
+| `session.mock(service)` | Get `MockBuilder` for service |
+| `session.chaos(service)` | Get `ChaosBuilder` for service |
+| `session.iam` | Get `IamBuilder` |
+
+### Supported services
+
+`dynamodb`, `s3`, `sqs`, `sns`, `ssm`, `secretsmanager`, `stepfunctions`
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-web-services-javascript-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "JavaScript testing SDK for local-web-services — subprocess-based AWS service fixtures for testing",
   "main": "src/index.js",
   "files": [

package/src/discovery/hcl.js

@@ -0,0 +1,149 @@
+"use strict";
+
+/**
+ * Minimal Terraform HCL parser for discovering AWS resources in .tf files.
+ *
+ * Supports the subset of HCL needed for common AWS resource types, including
+ * heredoc strings (<<MARKER ... MARKER) used for multi-line JSON definitions.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const RESOURCE_HEADER = /resource\s+"(?<type>[^"]+)"\s+"(?<logical>[^"]+)"\s*\{/;
+const ATTR_STR = /^\s*(?<key>\w+)\s*=\s*"(?<value>[^"]*)"/;
+const ATTR_BARE = /^\s*(?<key>\w+)\s*=\s*(?<value>\S+)/;
+const ATTR_HEREDOC = /^\s*(?<key>\w+)\s*=\s*<<(?<marker>\w+)\s*$/;
+
+/**
+ * Parse all .tf files in `projectDir` and return a resource spec object with
+ * discovered AWS resources ready for use with LwsSession.
+ *
+ * @param {string} projectDir
+ * @returns {{ stateMachines?: Array<{ name: string, definition?: string, roleArn?: string }> }}
+ */
+function discoverHcl(projectDir) {
+  const tfFiles = [];
+
+  function findTfFiles(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory() && !entry.name.startsWith(".")) {
+        findTfFiles(path.join(dir, entry.name));
+      } else if (entry.name.endsWith(".tf")) {
+        tfFiles.push(path.join(dir, entry.name));
+      }
+    }
+  }
+
+  findTfFiles(projectDir);
+
+  if (tfFiles.length === 0) {
+    throw new Error(
+      `No .tf files found in ${projectDir}. ` +
+        "Make sure you point to the directory containing your Terraform files."
+    );
+  }
+
+  const resources = [];
+  for (const tfFile of tfFiles) {
+    resources.push(...parseTfFile(tfFile));
+  }
+
+  return classifyResources(resources);
+}
+
+function parseTfFile(filePath) {
+  const text = fs.readFileSync(filePath, "utf-8");
+  const lines = text.split("\n");
+  const results = [];
+  let i = 0;
+
+  while (i < lines.length) {
+    const m = RESOURCE_HEADER.exec(lines[i]);
+    if (m?.groups) {
+      const { type, logical } = m.groups;
+      const [attrs, nextI] = collectBlock(lines, i + 1);
+      results.push({ type, logical, attrs });
+      i = nextI;
+    } else {
+      i++;
+    }
+  }
+
+  return results;
+}
+
+function collectBlock(lines, start) {
+  const attrs = {};
+  let depth = 1;
+  let i = start;
+
+  while (i < lines.length && depth > 0) {
+    const line = lines[i];
+
+    // Handle heredoc (key = <<MARKER ... MARKER) before adjusting depth so
+    // JSON content inside the heredoc does not affect brace counting.
+    if (depth === 1) {
+      const mHeredoc = ATTR_HEREDOC.exec(line);
+      if (mHeredoc?.groups) {
+        const { key, marker } = mHeredoc.groups;
+        i++;
+        const heredocLines = [];
+        while (i < lines.length && lines[i].trimEnd() !== marker) {
+          heredocLines.push(lines[i]);
+          i++;
+        }
+        attrs[key] = heredocLines.join("\n");
+        i++; // skip the closing marker line
+        continue;
+      }
+    }
+
+    const opens = (line.match(/\{/g) ?? []).length;
+    const closes = (line.match(/\}/g) ?? []).length;
+    depth += opens - closes;
+
+    if (depth > 1) {
+      i++;
+      continue;
+    }
+    if (depth === 0) break;
+
+    const mStr = ATTR_STR.exec(line);
+    if (mStr?.groups) {
+      attrs[mStr.groups.key] = mStr.groups.value;
+    } else {
+      const mBare = ATTR_BARE.exec(line);
+      if (mBare?.groups) {
+        attrs[mBare.groups.key] = mBare.groups.value;
+      }
+    }
+    i++;
+  }
+
+  return [attrs, i + 1];
+}
+
+function classifyResources(resources) {
+  const spec = { stateMachines: [] };
+
+  for (const { type, attrs } of resources) {
+    if (type === "aws_sfn_state_machine") {
+      const sm = buildStateMachine(attrs);
+      if (sm) spec.stateMachines.push(sm);
+    }
+  }
+
+  return spec;
+}
+
+function buildStateMachine(attrs) {
+  if (!attrs["name"]) return null;
+  return {
+    name: attrs["name"],
+    definition: attrs["definition"] ?? "{}",
+    roleArn: attrs["role_arn"],
+  };
+}
+
+module.exports = { discoverHcl };

package/src/session.js

@@ -181,13 +181,49 @@ class LwsSession {
   /**
    * Create a session by discovering resources from a Terraform / HCL project.
    *
+   * Reads `.tf` files in `projectDir`, discovers AWS resources, starts ldk,
+   * and pre-creates the discovered resources so they are immediately available.
+   *
    * @param {string} [projectDir="."]
    * @returns {Promise<LwsSession>}
    */
   static async fromHcl(projectDir = ".") {
+    const { discoverHcl } = require("./discovery/hcl");
+
+    const resolvedDir = path.resolve(projectDir);
+    const spec = discoverHcl(resolvedDir);
+
     const basePort = await freePort();
-    const session = new LwsSession(basePort, projectDir, {});
-    await session._start("terraform");
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "lws-testing-"));
+    await generateTerraformConfig(tempDir, spec);
+
+    const session = new LwsSession(basePort, tempDir, spec);
+    session._tempDir = tempDir;
+    await session._start();
+
+    // Pre-create state machines discovered from the HCL files.
+    const sfnPort = basePort + SERVICE_OFFSETS["stepfunctions"];
+    for (const sm of spec.stateMachines ?? []) {
+      const definition =
+        typeof sm.definition === "object"
+          ? JSON.stringify(sm.definition)
+          : (sm.definition ?? "{}");
+      await fetch(`http://127.0.0.1:${sfnPort}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-amz-json-1.0",
+          "X-Amz-Target": "AWSStepFunctions.CreateStateMachine",
+        },
+        body: JSON.stringify({
+          name: sm.name,
+          definition,
+          roleArn:
+            sm.roleArn ?? "arn:aws:iam::000000000000:role/StepFunctionsRole",
+          type: "STANDARD",
+        }),
+      });
+    }
+
     return session;
   }