@terraforge/core 0.0.1

package/README.md

@@ -0,0 +1,116 @@
+
+# Infrastructure as code made fast & easy
+
+The core of Terraforge lives in `@terraforge/core`, with the Terraform bridge in `@terraforge/terraform`. Together they provide a fast, diff-friendly IaC workflow for AWS (and custom) stacks.
+
+## The problem
+
+The most used IaC solutions are slow & don't effectively leverage diffing to speed up their deployments.
+
+## Todo's
+- When a resource is being deleted inside a deployment we need to make sure that resources that depends on our deleted resource will be updated first.
+
+## Setup
+
+Install with (NPM):
+
+```
+npm i @terraforge/core @terraforge/terraform
+```
+
+## Example
+
+First, you need to create a workspace instance and pass in the cloud providers that you will use.
+We also need to give it a lock provider & state provider.
+
+- A cloud provider is used to create resources on a specific cloud provider. We have built-in cloud providers for AWS resources, but you could simply add your own as well.
+
+- The state provider is used for storing the latest deployment state.
+
+- The lock provider is used for acquiring a lock when you deploy your app. This will guarantee that multiple people can never deploy the same application at the same time.
+
+In this example, we will use a local file lock & state provider.
+
+```ts
+import { App, FileStateBackend, FileLockBackend, Stack, WorkSpace } from '@terraforge/core'
+import { Terraform, $ } from '@terraforge/terraform'
+
+const terraform = new Terraform({
+	providerLocation: './providers'
+})
+
+const aws = await terraform.install('hashicorp', 'aws', '5.93.0')
+
+const workspace = new WorkSpace({
+	providers: [
+		aws({
+			profile: "PROFILE",
+			region: "REGION"
+		})
+	],
+	backend: {
+		state: new FileStateBackend({ dir: './states' }),
+		lock: new FileLockBackend({ dir: './locks' }),
+	}
+})
+```
+
+With your workspace configuration ready we can now move on to defining your infrastructure.
+This example illustrates how simple it is to define multi-stack resources without worrying about cross-stack references.
+
+```ts
+const app = new App('todo-app')
+const storage = new Stack(app, 'storage')
+const list = new $.aws.s3.Bucket(storage, 'list', {})
+
+const items = new Stack(app, 'items')
+const todo = new $.aws.s3.BucketObject(items, 'item', {
+	bucket: list.bucket,
+	key: 'item-1',
+	content: JSON.stringify({
+		title: 'Write docs...',
+		done: true,
+	}),
+})
+```
+
+After defining your infrastructure, we can deploy our app.
+```ts
+await workspace.deploy(app)
+```
+
+Or destroy our app.
+```ts
+await workspace.delete(app)
+```
+
+Maybe you want to only deploy a subset of stacks.
+```ts
+await workspace.deploy(app, {
+	filters: ["storage"]
+})
+```
+
+## Production
+
+For production, we recommend you use a state & lock backend that stores your data in the cloud.
+An AWS DynamoDB table is perfect for storing locks.
+While AWS S3 is perfect for storing your state files.
+
+```ts
+const workspace = new WorkSpace({
+	providers: [...],
+	backend: {
+		lock: new DynamoLockBackend({
+  			region,
+  			credentials,
+  			tableName: 'awsless-locks',
+  		}),
+		state: new S3StateBackend({
+			region,
+			credentials,
+			bucket: 'awsless-state-UNIQUE_ID',
+		}),
+	}
+})
+```

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@terraforge/core",
+	"version": "0.0.1",
+	"type": "module",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"scripts": {
+		"build": "bunup src/index.ts --format esm --dts --clean --target node --packages external --out-dir ./dist",
+		"prepublish": "bun run build",
+		"test": "bun test"
+	},
+	"dependencies": {
+		"@aws-sdk/client-dynamodb": "3.363.0",
+		"@aws-sdk/client-s3": "^3.779.0",
+		"@aws-sdk/types": "3.329.0",
+		"@aws-sdk/util-dynamodb": "^3.777.0",
+		"async-on-exit": "^0.1.0",
+		"get-wild": "^3.0.2",
+		"graphology": "^0.26.0",
+		"graphology-dag": "^0.4.1",
+		"p-limit": "^6.2.0",
+		"proper-lockfile": "^4.1.2",
+		"uuid": "^11.1.0"
+	},
+	"devDependencies": {
+		"@types/proper-lockfile": "^4.1.4"
+	},
+	"files": [
+		"dist"
+	],
+	"license": "MIT"
+}