declastruct 1.0.0 → 1.1.0

package/dist/contract/cli/plan.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env tsx
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executePlanCommand = void 0;
+const bottleneck_1 = __importDefault(require("bottleneck"));
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const helpful_errors_1 = require("helpful-errors");
+const path_1 = require("path");
+const planChanges_1 = require("../../domain.operations/plan/planChanges");
+const log = console;
+/**
+ * .what = executes the plan command to generate an infrastructure change plan
+ * .why = provides CLI interface for planning infrastructure changes
+ * .note = requires wish file with getResources() and getProviders() exports
+ */
+const executePlanCommand = async ({ wishFilePath, planFilePath, }) => {
+    // resolve paths
+    const resolvedWishPath = (0, path_1.resolve)(process.cwd(), wishFilePath);
+    const resolvedPlanPath = (0, path_1.resolve)(process.cwd(), planFilePath);
+    // validate wish file exists
+    if (!(0, fs_1.existsSync)(resolvedWishPath)) {
+        throw new helpful_errors_1.BadRequestError(`Wish file not found: ${resolvedWishPath}`);
+    }
+    log.info('🌊 declastruct plan');
+    log.info(`   wish: ${resolvedWishPath}`);
+    log.info(`   plan: ${resolvedPlanPath}`);
+    log.info('');
+    // import wish file
+    const wish = await Promise.resolve(`${resolvedWishPath}`).then(s => __importStar(require(s)));
+    // validate exports
+    if (typeof wish.getResources !== 'function') {
+        throw new helpful_errors_1.BadRequestError('Wish file must export getResources() function');
+    }
+    if (typeof wish.getProviders !== 'function') {
+        throw new helpful_errors_1.BadRequestError('Wish file must export getProviders() function');
+    }
+    // get resources and providers
+    const resources = await wish.getResources();
+    const providers = await wish.getProviders();
+    // initialize providers
+    log.info('✨ start providers...');
+    await Promise.all(providers.map((p) => p.hooks.beforeAll()));
+    // create context
+    const context = {
+        bottleneck: new bottleneck_1.default({ maxConcurrent: 10 }),
+        log,
+    };
+    // plan changes (logs emitted in real-time by planChanges)
+    log.info('🔮 plan changes...');
+    log.info('');
+    const plan = await (0, planChanges_1.planChanges)({
+        resources,
+        providers,
+        wishFilePath: resolvedWishPath,
+    }, context);
+    // write plan to file
+    await (0, promises_1.writeFile)(resolvedPlanPath, JSON.stringify(plan, null, 2), 'utf-8');
+    // cleanup providers
+    log.info('✨ stop providers...');
+    await Promise.all(providers.map((p) => p.hooks.afterAll()));
+    // log summary
+    log.info('');
+    log.info(`🌊 planned for ${plan.changes.length} resources`);
+    log.info(`   into ${resolvedPlanPath}`);
+};
+exports.executePlanCommand = executePlanCommand;
+//# sourceMappingURL=plan.js.map

package/dist/contract/cli/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../../src/contract/cli/plan.ts"],"names":[],"mappings":"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"}

package/dist/contract/sdk/index.d.ts

@@ -1,3 +1,15 @@
-export * from './refs';
-export * from './sync/plan';
-export * from './sync/apply';
+export { IsoTimestamp } from '../../domain.objects/IsoTimestamp';
+export { DeclastructChange, DeclastructChangeAction, } from '../../domain.objects/DeclastructChange';
+export { DeclastructDao } from '../../domain.objects/DeclastructDao';
+export { DeclastructProvider } from '../../domain.objects/DeclastructProvider';
+export { DeclastructPlan } from '../../domain.objects/DeclastructPlan';
+export { ContextDeclastruct } from '../../domain.objects/ContextDeclastruct';
+export { getDaoByResource } from '../../domain.operations/plan/getDaoByResource';
+export { computeChange } from '../../domain.operations/plan/computeChange';
+export { planChanges } from '../../domain.operations/plan/planChanges';
+export { assertPlanStillValid } from '../../domain.operations/plan/validate';
+export { hashChanges } from '../../domain.operations/plan/hashChanges';
+export { extractResourcesFromPlan } from '../../domain.operations/plan/extractResourcesFromPlan';
+export { asIsoTimestamp } from '../../infra/asIsoTimestamp';
+export { applyChange } from '../../domain.operations/apply/applyChange';
+export { applyChanges } from '../../domain.operations/apply/applyChanges';

package/dist/contract/sdk/index.js

@@ -1,20 +1,34 @@
 "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("./refs"), exports);
-__exportStar(require("./sync/plan"), exports);
-__exportStar(require("./sync/apply"), exports);
+exports.applyChanges = exports.applyChange = exports.asIsoTimestamp = exports.extractResourcesFromPlan = exports.hashChanges = exports.assertPlanStillValid = exports.planChanges = exports.computeChange = exports.getDaoByResource = exports.DeclastructPlan = exports.DeclastructProvider = exports.DeclastructDao = exports.DeclastructChangeAction = exports.DeclastructChange = void 0;
+var DeclastructChange_1 = require("../../domain.objects/DeclastructChange");
+Object.defineProperty(exports, "DeclastructChange", { enumerable: true, get: function () { return DeclastructChange_1.DeclastructChange; } });
+Object.defineProperty(exports, "DeclastructChangeAction", { enumerable: true, get: function () { return DeclastructChange_1.DeclastructChangeAction; } });
+var DeclastructDao_1 = require("../../domain.objects/DeclastructDao");
+Object.defineProperty(exports, "DeclastructDao", { enumerable: true, get: function () { return DeclastructDao_1.DeclastructDao; } });
+var DeclastructProvider_1 = require("../../domain.objects/DeclastructProvider");
+Object.defineProperty(exports, "DeclastructProvider", { enumerable: true, get: function () { return DeclastructProvider_1.DeclastructProvider; } });
+var DeclastructPlan_1 = require("../../domain.objects/DeclastructPlan");
+Object.defineProperty(exports, "DeclastructPlan", { enumerable: true, get: function () { return DeclastructPlan_1.DeclastructPlan; } });
+// domain operations - plan
+var getDaoByResource_1 = require("../../domain.operations/plan/getDaoByResource");
+Object.defineProperty(exports, "getDaoByResource", { enumerable: true, get: function () { return getDaoByResource_1.getDaoByResource; } });
+var computeChange_1 = require("../../domain.operations/plan/computeChange");
+Object.defineProperty(exports, "computeChange", { enumerable: true, get: function () { return computeChange_1.computeChange; } });
+var planChanges_1 = require("../../domain.operations/plan/planChanges");
+Object.defineProperty(exports, "planChanges", { enumerable: true, get: function () { return planChanges_1.planChanges; } });
+var validate_1 = require("../../domain.operations/plan/validate");
+Object.defineProperty(exports, "assertPlanStillValid", { enumerable: true, get: function () { return validate_1.assertPlanStillValid; } });
+var hashChanges_1 = require("../../domain.operations/plan/hashChanges");
+Object.defineProperty(exports, "hashChanges", { enumerable: true, get: function () { return hashChanges_1.hashChanges; } });
+var extractResourcesFromPlan_1 = require("../../domain.operations/plan/extractResourcesFromPlan");
+Object.defineProperty(exports, "extractResourcesFromPlan", { enumerable: true, get: function () { return extractResourcesFromPlan_1.extractResourcesFromPlan; } });
+// infra
+var asIsoTimestamp_1 = require("../../infra/asIsoTimestamp");
+Object.defineProperty(exports, "asIsoTimestamp", { enumerable: true, get: function () { return asIsoTimestamp_1.asIsoTimestamp; } });
+// domain operations - apply
+var applyChange_1 = require("../../domain.operations/apply/applyChange");
+Object.defineProperty(exports, "applyChange", { enumerable: true, get: function () { return applyChange_1.applyChange; } });
+var applyChanges_1 = require("../../domain.operations/apply/applyChanges");
+Object.defineProperty(exports, "applyChanges", { enumerable: true, get: function () { return applyChanges_1.applyChanges; } });
 //# sourceMappingURL=index.js.map

package/dist/contract/sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contract/sdk/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yCAAuB;AACvB,8CAA4B;AAC5B,+CAA6B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contract/sdk/index.ts"],"names":[],"mappings":";;;AAEA,4EAGgD;AAF9C,sHAAA,iBAAiB,OAAA;AACjB,4HAAA,uBAAuB,OAAA;AAEzB,sEAAqE;AAA5D,gHAAA,cAAc,OAAA;AACvB,gFAA+E;AAAtE,0HAAA,mBAAmB,OAAA;AAC5B,wEAAuE;AAA9D,kHAAA,eAAe,OAAA;AAGxB,2BAA2B;AAC3B,kFAAiF;AAAxE,oHAAA,gBAAgB,OAAA;AACzB,4EAA2E;AAAlE,8GAAA,aAAa,OAAA;AACtB,wEAAuE;AAA9D,0GAAA,WAAW,OAAA;AACpB,kEAA6E;AAApE,gHAAA,oBAAoB,OAAA;AAC7B,wEAAuE;AAA9D,0GAAA,WAAW,OAAA;AACpB,kGAAiG;AAAxF,oIAAA,wBAAwB,OAAA;AAEjC,QAAQ;AACR,6DAA4D;AAAnD,gHAAA,cAAc,OAAA;AAEvB,4BAA4B;AAC5B,yEAAwE;AAA/D,0GAAA,WAAW,OAAA;AACpB,2EAA0E;AAAjE,4GAAA,YAAY,OAAA"}

package/dist/domain.objects/ContextDeclastruct.d.ts

@@ -0,0 +1,15 @@
+import Bottleneck from 'bottleneck';
+/**
+ * .what = standard context for all declastruct operations
+ * .why = provides concurrency control and log trail
+ * .note = bottleneck can be a single instance or separate instances for plan/apply operations
+ */
+export type ContextDeclastruct = {
+    /**
+     * concurrency control - either single bottleneck or separate for plan/apply
+     */
+    bottleneck: Bottleneck | {
+        onPlan: Bottleneck;
+        onApply: Bottleneck;
+    };
+};

package/dist/{domain/DeclastructContext.js → domain.objects/ContextDeclastruct.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=DeclastructContext.js.map
+//# sourceMappingURL=ContextDeclastruct.js.map

package/dist/domain.objects/ContextDeclastruct.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextDeclastruct.js","sourceRoot":"","sources":["../../src/domain.objects/ContextDeclastruct.ts"],"names":[],"mappings":""}

package/dist/domain.objects/ContextDeclastruct.test.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const bottleneck_1 = __importDefault(require("bottleneck"));
+describe('ContextDeclastruct', () => {
+    it('should accept single bottleneck configuration', () => {
+        const context = {
+            bottleneck: new bottleneck_1.default({ maxConcurrent: 5 }),
+        };
+        expect(context.bottleneck).toBeInstanceOf(bottleneck_1.default);
+    });
+    it('should accept split bottleneck configuration', () => {
+        const context = {
+            bottleneck: {
+                onPlan: new bottleneck_1.default({ maxConcurrent: 10 }),
+                onApply: new bottleneck_1.default({ maxConcurrent: 1 }),
+            },
+        };
+        expect(context.bottleneck).toHaveProperty('onPlan');
+        expect(context.bottleneck).toHaveProperty('onApply');
+        expect(context.bottleneck.onPlan).toBeInstanceOf(bottleneck_1.default);
+        expect(context.bottleneck.onApply).toBeInstanceOf(bottleneck_1.default);
+    });
+    it('should be able to intersect with ContextLogTrail', () => {
+        // type verification
+        const context = {
+            bottleneck: new bottleneck_1.default({ maxConcurrent: 5 }),
+            log: {
+                info: () => { },
+                warn: () => { },
+                error: () => { },
+                debug: () => { },
+            },
+        };
+        expect(context.bottleneck).toBeDefined();
+        expect(context.log).toBeDefined();
+    });
+});
+//# sourceMappingURL=ContextDeclastruct.test.js.map

package/dist/domain.objects/ContextDeclastruct.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextDeclastruct.test.js","sourceRoot":"","sources":["../../src/domain.objects/ContextDeclastruct.test.ts"],"names":[],"mappings":";;;;;AAAA,4DAAoC;AAKpC,QAAQ,CAAC,oBAAoB,EAAE,GAAG,EAAE;IAClC,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,OAAO,GAAuB;YAClC,UAAU,EAAE,IAAI,oBAAU,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;SACjD,CAAC;QAEF,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,cAAc,CAAC,oBAAU,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,OAAO,GAAuB;YAClC,UAAU,EAAE;gBACV,MAAM,EAAE,IAAI,oBAAU,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;gBAC7C,OAAO,EAAE,IAAI,oBAAU,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;aAC9C;SACF,CAAC;QAEF,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QACpD,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;QACrD,MAAM,CAAE,OAAO,CAAC,UAAkB,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,oBAAU,CAAC,CAAC;QACtE,MAAM,CAAE,OAAO,CAAC,UAAkB,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,oBAAU,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,oBAAoB;QACpB,MAAM,OAAO,GAAyC;YACpD,UAAU,EAAE,IAAI,oBAAU,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;YAChD,GAAG,EAAE;gBACH,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;gBACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;gBACd,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;gBACf,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;aAChB;SACF,CAAC;QAEF,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;QACzC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/domain.objects/DeclastructChange.d.ts

@@ -0,0 +1,73 @@
+import { DomainEntity, DomainLiteral } from 'domain-objects';
+/**
+ * .what = actions that can be proposed for a resource
+ * .why = clearly defines the type of change declastruct will execute
+ */
+export declare enum DeclastructChangeAction {
+    /**
+     * keep the resource as is
+     */
+    KEEP = "KEEP",
+    /**
+     * create a new resource
+     */
+    CREATE = "CREATE",
+    /**
+     * update an existing resource
+     */
+    UPDATE = "UPDATE",
+    /**
+     * destroy an existing resource
+     */
+    DESTROY = "DESTROY",
+    /**
+     * replace an existing resource (delete then create)
+     */
+    REPLACE = "REPLACE"
+}
+/**
+ * .what = describes a single change required to align remote state with desired state
+ * .why = enables observable, auditable infrastructure changes
+ */
+export interface DeclastructChange<TResource extends DomainEntity<any> = DomainEntity<any>> {
+    /**
+     * which resource this change is for
+     */
+    forResource: {
+        /**
+         * class name of the resource being changed
+         */
+        class: string;
+        /**
+         * scannable identifier of this specific resource
+         */
+        slug: string;
+    };
+    /**
+     * action to execute
+     */
+    action: DeclastructChangeAction;
+    /**
+     * the states of the resource
+     */
+    state: {
+        /**
+         * the desired state of the resource
+         *
+         * .note = null if the resource should be deleted
+         */
+        desired: TResource | null;
+        /**
+         * the remote state of the resource
+         *
+         * .note = null if the resource doesn't exist remotely
+         */
+        remote: TResource | null;
+        /**
+         * human-readable diff of changes
+         */
+        difference: string | null;
+    };
+}
+export declare class DeclastructChange<TResource extends DomainEntity<any> = DomainEntity<any>> extends DomainLiteral<DeclastructChange<TResource>> implements DeclastructChange<TResource> {
+}

package/dist/domain.objects/DeclastructChange.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeclastructChange = exports.DeclastructChangeAction = void 0;
+const domain_objects_1 = require("domain-objects");
+/**
+ * .what = actions that can be proposed for a resource
+ * .why = clearly defines the type of change declastruct will execute
+ */
+var DeclastructChangeAction;
+(function (DeclastructChangeAction) {
+    /**
+     * keep the resource as is
+     */
+    DeclastructChangeAction["KEEP"] = "KEEP";
+    /**
+     * create a new resource
+     */
+    DeclastructChangeAction["CREATE"] = "CREATE";
+    /**
+     * update an existing resource
+     */
+    DeclastructChangeAction["UPDATE"] = "UPDATE";
+    /**
+     * destroy an existing resource
+     */
+    DeclastructChangeAction["DESTROY"] = "DESTROY";
+    /**
+     * replace an existing resource (delete then create)
+     */
+    DeclastructChangeAction["REPLACE"] = "REPLACE";
+})(DeclastructChangeAction || (exports.DeclastructChangeAction = DeclastructChangeAction = {}));
+class DeclastructChange extends domain_objects_1.DomainLiteral {
+}
+exports.DeclastructChange = DeclastructChange;
+//# sourceMappingURL=DeclastructChange.js.map

package/dist/domain.objects/DeclastructChange.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclastructChange.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructChange.ts"],"names":[],"mappings":";;;AAAA,mDAA6D;AAE7D;;;GAGG;AACH,IAAY,uBAyBX;AAzBD,WAAY,uBAAuB;IACjC;;OAEG;IACH,wCAAa,CAAA;IAEb;;OAEG;IACH,4CAAiB,CAAA;IAEjB;;OAEG;IACH,4CAAiB,CAAA;IAEjB;;OAEG;IACH,8CAAmB,CAAA;IAEnB;;OAEG;IACH,8CAAmB,CAAA;AACrB,CAAC,EAzBW,uBAAuB,uCAAvB,uBAAuB,QAyBlC;AAsDD,MAAa,iBAGX,SAAQ,8BAA2C;CACT;AAJ5C,8CAI4C"}

package/dist/domain.objects/DeclastructChange.test.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const domain_objects_1 = require("domain-objects");
+const DeclastructChange_1 = require("./DeclastructChange");
+describe('DeclastructChange', () => {
+    describe('DeclastructChangeAction', () => {
+        it('should export all 5 action types', () => {
+            expect(DeclastructChange_1.DeclastructChangeAction.KEEP).toBe('KEEP');
+            expect(DeclastructChange_1.DeclastructChangeAction.CREATE).toBe('CREATE');
+            expect(DeclastructChange_1.DeclastructChangeAction.UPDATE).toBe('UPDATE');
+            expect(DeclastructChange_1.DeclastructChangeAction.DESTROY).toBe('DESTROY');
+            expect(DeclastructChange_1.DeclastructChangeAction.REPLACE).toBe('REPLACE');
+        });
+    });
+    describe('DeclastructChange class', () => {
+        class DemoResource extends domain_objects_1.DomainEntity {
+        }
+        DemoResource.unique = ['id'];
+        it('should build a change with all required properties', () => {
+            const change = new DeclastructChange_1.DeclastructChange({
+                forResource: {
+                    class: DemoResource.constructor.name,
+                    slug: 'demo-1',
+                },
+                action: DeclastructChange_1.DeclastructChangeAction.CREATE,
+                state: {
+                    desired: new DemoResource({ id: 'demo-1', name: 'Demo' }),
+                    remote: null,
+                    difference: null,
+                },
+            });
+            expect(change.forResource.class).toBe(DemoResource.constructor.name);
+            expect(change.forResource.slug).toBe('demo-1');
+            expect(change.action).toBe(DeclastructChange_1.DeclastructChangeAction.CREATE);
+            expect(change.state.desired).toBeDefined();
+            expect(change.state.remote).toBeNull();
+            expect(change.state.difference).toBeNull();
+        });
+        it('should handle KEEP action with matching desired and remote state', () => {
+            const resource = new DemoResource({ id: 'demo-2', name: 'Demo' });
+            const change = new DeclastructChange_1.DeclastructChange({
+                forResource: {
+                    class: DemoResource.constructor.name,
+                    slug: 'demo-2',
+                },
+                action: DeclastructChange_1.DeclastructChangeAction.KEEP,
+                state: {
+                    desired: resource,
+                    remote: resource,
+                    difference: null,
+                },
+            });
+            expect(change.action).toBe(DeclastructChange_1.DeclastructChangeAction.KEEP);
+            expect(change.state.difference).toBeNull();
+            expect(change.state.desired).toBe(change.state.remote);
+        });
+    });
+});
+//# sourceMappingURL=DeclastructChange.test.js.map

package/dist/domain.objects/DeclastructChange.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclastructChange.test.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructChange.test.ts"],"names":[],"mappings":"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"}

package/dist/domain.objects/DeclastructDao.d.ts

@@ -0,0 +1,39 @@
+import { DomainEntity, DomainLiteral, Ref, Refable, RefByPrimary, RefByUnique } from 'domain-objects';
+import { HasMetadata } from 'type-fns';
+/**
+ * .what = standardized data access interface for any resource type
+ * .why = enforces idempotent semantics and consistent access patterns across all providers
+ * .note = TResourceClass is the class constructor (e.g., typeof MyResource) with static unique/primary properties
+ */
+export interface DeclastructDao<TResource extends DomainEntity<any>, TResourceClass extends Refable<any, any, any>, TContext = never> {
+    get: {
+        /**
+         * required - fetch by unique keys (enables idempotency)
+         */
+        byUnique: (input: RefByUnique<TResourceClass>, context: TContext) => Promise<TResource | null>;
+        /**
+         * optional - fetch by primary keys (if resource supports them)
+         */
+        byPrimary?: (input: RefByPrimary<TResourceClass>, context: TContext) => Promise<TResource | null>;
+        /**
+         * required - fetch by any supported reference type
+         */
+        byRef: (input: Ref<TResourceClass>, context: TContext) => Promise<TResource | null>;
+    };
+    set: {
+        /**
+         * required - find or insert resource (idempotent create)
+         */
+        finsert: (input: TResource, context: TContext) => Promise<HasMetadata<TResource>>;
+        /**
+         * optional - create or update resource (idempotent upsert)
+         */
+        upsert?: (input: TResource, context: TContext) => Promise<HasMetadata<TResource>>;
+        /**
+         * optional - delete resource
+         */
+        delete?: (input: Ref<TResourceClass>, context: TContext) => Promise<void>;
+    };
+}
+export declare class DeclastructDao<TResource extends DomainEntity<any>, TResourceClass extends Refable<any, any, any>, TContext> extends DomainLiteral<DeclastructDao<TResource, TResourceClass, TContext>> implements DeclastructDao<TResource, TResourceClass, TContext> {
+}

package/dist/domain.objects/DeclastructDao.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeclastructDao = void 0;
+const domain_objects_1 = require("domain-objects");
+class DeclastructDao extends domain_objects_1.DomainLiteral {
+}
+exports.DeclastructDao = DeclastructDao;
+//# sourceMappingURL=DeclastructDao.js.map

package/dist/domain.objects/DeclastructDao.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclastructDao.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructDao.ts"],"names":[],"mappings":";;;AAAA,mDAOwB;AA+DxB,MAAa,cAKX,SAAQ,8BAAkE;CACT;AANnE,wCAMmE"}

package/dist/domain.objects/DeclastructDao.test.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const domain_objects_1 = require("domain-objects");
+describe('DeclastructDao', () => {
+    class DemoResource extends domain_objects_1.DomainEntity {
+    }
+    DemoResource.unique = ['id'];
+    it('should implement the interface structure', () => {
+        // type verification
+        const dao = {
+            get: {
+                byUnique: async () => null,
+                byRef: async () => null,
+            },
+            set: {
+                finsert: async (input) => input,
+            },
+        };
+        expect(dao.get.byUnique).toBeDefined();
+        expect(dao.get.byRef).toBeDefined();
+        expect(dao.set.finsert).toBeDefined();
+    });
+    it('should support optional methods', () => {
+        // type verification
+        const dao = {
+            get: {
+                byUnique: async () => null,
+                byPrimary: async () => null,
+                byRef: async () => null,
+            },
+            set: {
+                finsert: async (input) => input,
+                upsert: async (input) => input,
+                delete: async () => { },
+            },
+        };
+        expect(dao.get.byPrimary).toBeDefined();
+        expect(dao.set.upsert).toBeDefined();
+        expect(dao.set.delete).toBeDefined();
+    });
+});
+//# sourceMappingURL=DeclastructDao.test.js.map

package/dist/domain.objects/DeclastructDao.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclastructDao.test.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructDao.test.ts"],"names":[],"mappings":";;AAAA,mDAA8C;AAI9C,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAK9B,MAAM,YACJ,SAAQ,6BAA0B;;IAGpB,mBAAM,GAAG,CAAC,IAAI,CAAU,CAAC;IAGzC,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,oBAAoB;QACpB,MAAM,GAAG,GAAsD;YAC7D,GAAG,EAAE;gBACH,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI;gBAC1B,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI;aACxB;YACD,GAAG,EAAE;gBACH,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAY;aACvC;SACF,CAAC;QAEF,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,oBAAoB;QACpB,MAAM,GAAG,GAAsD;YAC7D,GAAG,EAAE;gBACH,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI;gBAC1B,SAAS,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI;gBAC3B,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI;aACxB;YACD,GAAG,EAAE;gBACH,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAY;gBACtC,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,KAAY;gBACrC,MAAM,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;aACvB;SACF,CAAC;QAEF,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/domain.objects/DeclastructPlan.d.ts

@@ -0,0 +1,35 @@
+import { DomainEntity } from 'domain-objects';
+import { DeclastructChange } from './DeclastructChange';
+import { IsoTimestamp } from './IsoTimestamp';
+/**
+ * .what = collection of all planned changes required to fulfill a wish
+ * .why = enables review, version control, and validation of infrastructure changes
+ */
+export interface DeclastructPlan {
+    /**
+     * hash of the proposed changes (for validation on apply)
+     */
+    hash: string;
+    /**
+     * timestamp when plan was created
+     */
+    createdAt: IsoTimestamp;
+    /**
+     * reference to the wish file
+     */
+    wish: {
+        /**
+         * file path URI to the wish file containing resources and providers
+         */
+        uri: string;
+    };
+    /**
+     * all proposed changes
+     */
+    changes: DeclastructChange[];
+}
+export declare class DeclastructPlan extends DomainEntity<DeclastructPlan> implements DeclastructPlan {
+    static primary: readonly ["hash"];
+    static unique: readonly ["hash"];
+    static updatable: readonly [];
+}

package/dist/domain.objects/DeclastructPlan.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeclastructPlan = void 0;
+const domain_objects_1 = require("domain-objects");
+class DeclastructPlan extends domain_objects_1.DomainEntity {
+}
+exports.DeclastructPlan = DeclastructPlan;
+DeclastructPlan.primary = ['hash'];
+DeclastructPlan.unique = ['hash'];
+DeclastructPlan.updatable = [];
+//# sourceMappingURL=DeclastructPlan.js.map

package/dist/domain.objects/DeclastructPlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclastructPlan.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructPlan.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAoC9C,MAAa,eACX,SAAQ,6BAA6B;;AADvC,0CAOC;AAHe,uBAAO,GAAG,CAAC,MAAM,CAAU,CAAC;AAC5B,sBAAM,GAAG,CAAC,MAAM,CAAU,CAAC;AAC3B,yBAAS,GAAG,EAAW,CAAC"}

package/dist/domain.objects/DeclastructPlan.test.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const DeclastructPlan_1 = require("./DeclastructPlan");
+describe('DeclastructPlan', () => {
+    it('should build a plan with all required properties', () => {
+        const plan = new DeclastructPlan_1.DeclastructPlan({
+            hash: 'abc123',
+            createdAt: '2025-11-22T10:30:00.000Z',
+            wish: { uri: '/path/to/wish.ts' },
+            changes: [],
+        });
+        expect(plan.hash).toBe('abc123');
+        expect(plan.createdAt).toBe('2025-11-22T10:30:00.000Z');
+        expect(plan.wish.uri).toBe('/path/to/wish.ts');
+        expect(plan.changes).toEqual([]);
+    });
+    it('should have unique key set to hash', () => {
+        expect(DeclastructPlan_1.DeclastructPlan.unique).toEqual(['hash']);
+    });
+    it('should extend DomainEntity', () => {
+        const plan = new DeclastructPlan_1.DeclastructPlan({
+            hash: 'test-hash',
+            createdAt: '2025-11-22T10:30:00.000Z',
+            wish: { uri: '/test' },
+            changes: [],
+        });
+        // domain entities should have constructor.name
+        expect(plan.constructor.name).toBe('DeclastructPlan');
+    });
+});
+//# sourceMappingURL=DeclastructPlan.test.js.map

package/dist/domain.objects/DeclastructPlan.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclastructPlan.test.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructPlan.test.ts"],"names":[],"mappings":";;AAAA,uDAAoD;AAEpD,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,IAAI,GAAG,IAAI,iCAAe,CAAC;YAC/B,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,0BAA0B;YACrC,IAAI,EAAE,EAAE,GAAG,EAAE,kBAAkB,EAAE;YACjC,OAAO,EAAE,EAAE;SACZ,CAAC,CAAC;QAEH,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,iCAAe,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,IAAI,GAAG,IAAI,iCAAe,CAAC;YAC/B,IAAI,EAAE,WAAW;YACjB,SAAS,EAAE,0BAA0B;YACrC,IAAI,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE;YACtB,OAAO,EAAE,EAAE;SACZ,CAAC,CAAC;QAEH,+CAA+C;QAC/C,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}