declastruct 1.1.0 → 1.1.2

package/bin/run

@@ -0,0 +1,4 @@
+#!/usr/bin/env tsx
+import { invoke } from '../dist/contract/cli/invoke';
+
+void invoke({ args: process.argv.slice(2) });

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './contract/sdk';

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./contract/sdk"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "declastruct",
   "author": "ehmpathy",
   "description": "Add declarative control to any resource constructs. Declare, plan, and apply within an observable pit-of-success.",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "repository": "ehmpathy/declastruct",
   "homepage": "https://github.com/ehmpathy/declastruct",
   "keywords": [
@@ -17,7 +17,12 @@
   "engines": {
     "node": ">=8.0.0"
   },
+  "types": "dist/index.d.ts",
+  "bin": {
+    "declastruct": "./bin/run"
+  },
   "files": [
+    "/bin",
     "/dist"
   ],
   "scripts": {

package/readme.md

@@ -3,74 +3,250 @@
 ![test](https://github.com/ehmpathy/declastruct/workflows/test/badge.svg)
 ![publish](https://github.com/ehmpathy/declastruct/workflows/publish/badge.svg)
 
-Add declarative control to any resource constructs. Declare, plan, and apply within an observable pit-of-success.
+declarative control for any resource constructs, batteries included
+
+# intro
+
+Add declarative control to any resource construct. Declare, plan, and apply within an observable pit-of-success.
 
 Declare the structures you want. Plan to see the changes required. Apply to make it so 🪄
 
-# install
+
+## what is it?
+
+`declastruct` is a framework for managing any resource construct declaratively using TypeScript.
+
+declare what you want, plan the changes, and apply them safely — all without managing separate state files or learning a new language.
+
+works with:
+- **infrastructure** — AWS, GCP, Azure resources
+- **SaaS platforms** — Stripe customers, GitHub repos, Slack channels, etc
+- **databases** — application data models
+- **any API** — anything with a remote state you want to control
+
+think Terraform, but:
+- **no state files to manage** — compares directly against live remote state
+- **no new language to learn** — uses TypeScript and your existing domain objects
+- **pit-of-success by default** — enforces idempotency, clear unique keys, and safe operations
+- **not just infrastructure** — works with any resource construct (saas, databases, apis, etc)
+
+# usage
+
+## install
 
 ```sh
 npm install declastruct --save-dev
 ```
 
-# use
+## use
 
-### 1. declare ✨
+### 1. **declare** your desired state ✨
 
-declare the resources you wish to have and how you wish to have them
+define resource constructs with strongly-typed domain objects:
 
 ```ts
 import { getDeclastructAwsProvider, DeclaredAwsS3Bucket } from 'declastruct-aws';
+import { getDeclastructStripeProvider, DeclaredStripeCustomer } from 'declastruct-stripe';
 
-// declare the providers that support your resources
+// define which providers support your resource constructs
 export const getProviders = async () => [
-    await getDeclastructAwsProvider({
-      profile: process.env.AWS_PROFILE,
-    })
-  ]
-
-// declare the resources in the states you want them
+  await getDeclastructAwsProvider({
+    profile: process.env.AWS_PROFILE,
+  }),
+  await getDeclastructStripeProvider({
+    apiKey: process.env.STRIPE_SECRET_KEY,
+  }),
+];
+
+// declare the resource constructs you want and their desired state
 export const getResources = async () => {
   const bucket = DeclaredAwsS3Bucket.as({
     name: 'your-s3-bucket',
+    versioning: true,
+    encryption: 'AES256',
   });
-  // declare other resources you wish to have
 
-  return [
-    bucket,
-    // ... all the resources you wish for will go here
-  ],
-}
+  const customer = DeclaredStripeCustomer.as({
+    email: 'user@example.com',
+    name: 'John Doe',
+    metadata: { source: 'app-web' },
+  });
+
+  return [bucket, customer];
+};
 ```
 
-### 2. plan 🔮
+### 2. **plan** the required changes 🔮
 
-plan how to achieve the wish of resources you've declared
+see exactly what will change before applying:
 
 ```sh
-npx declastruct plan --wish provision/resources.ts --into provision/.temp/plan.json
+npx declastruct plan \
+  --wish provision/resources.ts \
+  --into provision/.temp/plan.json
 ```
 
-### 3. apply 🪄
+output:
+```
+planned changes:
+  CREATE: DeclaredAwsS3Bucket.your-s3-bucket
+    + name: "your-s3-bucket"
+    + versioning: true
+    + encryption: "AES256"
+
+  CREATE: DeclaredStripeCustomer.user@example.com
+    + email: "user@example.com"
+    + name: "John Doe"
+    + metadata: { source: "app-web" }
+```
 
-apply the plan to fulfill the wish
+### 3. **apply** the plan 🪄
+
+execute the plan to make your desired state reality:
 
 ```sh
 npx declastruct apply --plan provision/.temp/plan.json
 ```
 
-# benefits
+# benefits - why declastruct?
+
+## summary
+
+✅ **stateless** — no state files to manage, compare directly against reality
+
+✅ **type-safe** — full TypeScript support with domain objects
+
+✅ **idempotent** — safe to run plans multiple times
+
+✅ **observable** — see exactly what will change before applying
+
+✅ **composable** — reuse domain objects and operations across application code and resource management
+
+✅ **pit-of-success** — enforced best practices via idempotent dao interfaces
+
+✅ **universal** — works with any resource construct (infrastructure, saas platforms, databases, apis, etc)
+
+
+## details
+
+### no state file management
+
+traditional declarative tools (like Terraform) require maintaining a separate state file that tracks what resources exist. this creates problems:
+- state files can drift from reality
+- state locking issues in team environments
+- state files must be carefully secured and backed up
+
+**declastruct eliminates state files entirely.** it compares your desired resource constructs directly against live remote state using unique keys, so the source of truth is always reality itself.
+
+### use your existing domain language
+
+instead of learning HCL, YAML, or another DSL:
+- declare resource constructs as TypeScript using `domain-objects`
+- reuse the same domain objects across your application code and remote resource management
+- leverage TypeScript's type safety, IDE autocomplete, and refactoring tools
+- compose and test resource definitions like any other code
+
+### enforced best practices
+
+declastruct providers follow a pit-of-success pattern that guarantees:
+
+**idempotency** — all operations can be safely retried
+- `finsert`: find-or-insert (safe create)
+- `upsert`: update-or-insert (safe update)
+- running the same plan multiple times produces the same result
+
+**explicit unique keys** — every resource declares how to uniquely identify it
+- prevents accidental duplicates
+- enables accurate comparison against live state
+- makes resource relationships clear, typesafe, and composable
+
+**observable change plans** — see exactly what will change before applying
+- diff view shows before & after for each resource
+- change actions: CREATE, UPDATE, KEEP, DESTROY
+- no surprises in production
+
+### provider ecosystem
+
+declastruct is designed to support any resource construct through adapters:
+
+**available providers:**
+- `declastruct-aws` — AWS infrastructure (S3, Lambda, RDS, EC2, etc.)
+- `declastruct-stripe` — Stripe SaaS resources (customers, subscriptions, products, etc.)
+- `declastruct-github` — Github resources (repos, branches, protection, etc.)
+- etc
+
+**build your own provider** for any resource construct (GitHub repos, Slack channels, database records, etc.) by implementing the `DeclastructDao` and `DeclastructProvider` interfaces.
+
+## use cases
+
+- **infrastructure as code** — manage AWS, GCP, Azure resources declaratively
+- **SaaS platform management** — manage Stripe customers, GitHub repos, Slack channels, etc declaratively
+- **database state management** — control database resource states declaratively
+- **api state management** — control remote resource state through api's declaratively
+- **multi-platform orchestration** — coordinate resources across different providers in one plan
+
+
+# concepts
+
+## domain
+
+### DeclastructDao
+
+the core abstraction that defines how to interact with a resource type:
+
+```ts
+interface DeclastructDao<TResource, TResourceClass, TContext> {
+  get: {
+    byUnique: (ref: RefByUnique, context) => Promise<TResource | null>;
+    byPrimary?: (ref: RefByPrimary, context) => Promise<TResource | null>;
+    byRef: (ref: Ref, context) => Promise<TResource | null>;
+  };
+  set: {
+    finsert: (resource: TResource, context) => Promise<TResource>;
+    upsert?: (resource: TResource, context) => Promise<TResource>;
+    delete?: (ref: Ref, context) => Promise<void>;
+  };
+}
+```
+
+every resource class gets a DeclastructDao that enforces safe, idempotent operations.
+
+### DeclastructProvider
+
+bundles related DAOs and provider context:
+
+```ts
+interface DeclastructProvider<TDaos, TContext> {
+  name: string;                    // provider identifier
+  daos: TDaos;                     // map of resource types to DAOs
+  context: TContext;               // auth, region, etc.
+  hooks: {
+    beforeAll: () => Promise<void>;
+    afterAll: () => Promise<void>;
+  };
+}
+```
+
+### DeclastructPlan
+
+captures the changes needed to achieve desired state:
+
+```ts
+interface DeclastructPlan {
+  changes: DeclastructChange[];    // ordered list of changes
+  createdAt: IsoTimestamp;         // when plan was created
+  hash: string;                    // fingerprint for validation
+}
+```
+
+each `DeclastructChange` includes:
+- `action`: CREATE | UPDATE | KEEP | DESTROY
+- `forResource`: which resource this affects
+- `state.desired`: what you want
+- `state.remote`: what exists now
+- `state.difference`: human-readable diff
 
-- no dedicated state required
-  - looks at the source of truth directly
-  - leverages unique keys of resources to understand remote state automatically and eliminate the middleman
 
-- no new language syntax required
-  - no awkward new-language limitations
-  - reuse your existing domain language to manage your resources
+## inspiration
 
-- pit of success adapters
-  - each repo that implements a declastruct adapter to control their remote state follows a pit of success
-  - idempotency is required on operations, to guarantee they operate safely
-  - clear declaration of unique and primary keys is required, to guarantee readability, composability, and true comparisons against reality
-  - not only can you use them via declastruct, you can leverage them directly as well
+inspired by Terraform's declarative approach, but designed to eliminate state management overhead, work with any resource construct, and leverage TypeScript's type system for safer declarative resource management.