declastruct 1.4.5 → 1.5.1

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

@@ -4,3 +4,5 @@ export { DeclastructDao } from '../../domain.objects/DeclastructDao';
 export { DeclastructPlan } from '../../domain.objects/DeclastructPlan';
 export { DeclastructProvider } from '../../domain.objects/DeclastructProvider';
 export type { IsoTimestamp } from '../../domain.objects/IsoTimestamp';
+export { getRefByPrimary } from '../../domain.operations/ref/getRefByPrimary';
+export { getRefByUnique } from '../../domain.operations/ref/getRefByUnique';

package/dist/contract/sdk/index.js

@@ -1,7 +1,7 @@
 "use strict";
 // domain objects
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DeclastructProvider = exports.DeclastructPlan = exports.DeclastructDao = exports.DeclastructChangeAction = exports.DeclastructChange = void 0;
+exports.getRefByUnique = exports.getRefByPrimary = exports.DeclastructProvider = exports.DeclastructPlan = 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; } });
@@ -11,4 +11,9 @@ var DeclastructPlan_1 = require("../../domain.objects/DeclastructPlan");
 Object.defineProperty(exports, "DeclastructPlan", { enumerable: true, get: function () { return DeclastructPlan_1.DeclastructPlan; } });
 var DeclastructProvider_1 = require("../../domain.objects/DeclastructProvider");
 Object.defineProperty(exports, "DeclastructProvider", { enumerable: true, get: function () { return DeclastructProvider_1.DeclastructProvider; } });
+// domain operations
+var getRefByPrimary_1 = require("../../domain.operations/ref/getRefByPrimary");
+Object.defineProperty(exports, "getRefByPrimary", { enumerable: true, get: function () { return getRefByPrimary_1.getRefByPrimary; } });
+var getRefByUnique_1 = require("../../domain.operations/ref/getRefByUnique");
+Object.defineProperty(exports, "getRefByUnique", { enumerable: true, get: function () { return getRefByUnique_1.getRefByUnique; } });
 //# 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,iBAAiB;;;AAGjB,4EAGgD;AAF9C,sHAAA,iBAAiB,OAAA;AACjB,4HAAA,uBAAuB,OAAA;AAEzB,sEAAqE;AAA5D,gHAAA,cAAc,OAAA;AACvB,wEAAuE;AAA9D,kHAAA,eAAe,OAAA;AACxB,gFAA+E;AAAtE,0HAAA,mBAAmB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contract/sdk/index.ts"],"names":[],"mappings":";AAAA,iBAAiB;;;AAGjB,4EAGgD;AAF9C,sHAAA,iBAAiB,OAAA;AACjB,4HAAA,uBAAuB,OAAA;AAEzB,sEAAqE;AAA5D,gHAAA,cAAc,OAAA;AACvB,wEAAuE;AAA9D,kHAAA,eAAe,OAAA;AACxB,gFAA+E;AAAtE,0HAAA,mBAAmB,OAAA;AAG5B,oBAAoB;AACpB,+EAA8E;AAArE,kHAAA,eAAe,OAAA;AACxB,6EAA4E;AAAnE,gHAAA,cAAc,OAAA"}

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

@@ -1,4 +1,4 @@
-import { type DomainEntity, DomainLiteral, type Ref, type Refable, type RefByPrimary, type RefByUnique } from 'domain-objects';
+import { DomainLiteral, type Ref, type Refable, type RefByPrimary, type RefByUnique } from 'domain-objects';
 import type { HasMetadata } from 'type-fns';
 /**
  * .what = standardized data access interface for any resource type
@@ -7,37 +7,90 @@ import type { HasMetadata } from 'type-fns';
  *
  * .note =
  *   - TResourceClass is the class constructor (e.g., typeof MyResource) with static unique/primary properties
- *   - uses method syntax in the get & set for bivariance, to enable assignment to DeclastructDao<any, any, any>
+ *   - uses method syntax in the get & set for bivariance, to enable assignment to DeclastructDao<any, any>
  */
-export interface DeclastructDao<TResource extends DomainEntity<any>, TResourceClass extends Refable<any, any, any>, TContext = never> {
+export interface DeclastructDao<TResourceClass extends Refable<any, any, any>, TContext = never> {
+    /**
+     * .what = the domain object class this dao operates on
+     * .why = enables downstream operations (like getRefByPrimary) to access static properties
+     */
+    dobj: TResourceClass;
+    /**
+     * .what = read operations for fetching resources and resolving refs
+     * .why = provides consistent, type-safe access to remote state
+     */
     get: {
         /**
-         * required - fetch by unique keys (enables idempotency)
+         * .what = fetch a single resource by reference
+         * .why = enables looking up current state of a resource
          */
-        byUnique(input: RefByUnique<TResourceClass>, context: TContext): Promise<TResource | null>;
+        one: {
+            /**
+             * .what = fetch by unique keys
+             * .why = enables idempotent lookups via natural keys
+             */
+            byUnique(input: RefByUnique<TResourceClass>, context: TContext): Promise<InstanceType<TResourceClass> | null>;
+            /**
+             * .what = fetch by primary keys
+             * .why = enables efficient lookups when primary key is known
+             *
+             * .note = set to null if resource lacks primary keys (forces explicit decision)
+             */
+            byPrimary: null | ((input: RefByPrimary<TResourceClass>, context: TContext) => Promise<InstanceType<TResourceClass> | null>);
+            /**
+             * .what = fetch by any supported reference type
+             * .why = enables flexible lookups when ref type is not known at compile time
+             */
+            byRef(input: Ref<TResourceClass>, context: TContext): Promise<InstanceType<TResourceClass> | null>;
+        };
         /**
-         * optional - fetch by primary keys (if resource supports them)
+         * .what = ref resolution utilities for converting between ref types
+         * .why = enables working with generic Ref<T> while resolving to specific RefByPrimary/RefByUnique when needed
+         *
+         * .note = set methods to null if resource lacks primary keys (forces explicit decision)
          */
-        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>;
+        ref: {
+            /**
+             * .what = resolve any ref to RefByPrimary
+             * .why = enables getting primary key from any ref type
+             *
+             * .note = set to null if resource lacks primary keys
+             */
+            byPrimary: null | ((input: Ref<TResourceClass>, context: TContext) => Promise<RefByPrimary<TResourceClass>>);
+            /**
+             * .what = resolve any ref to RefByUnique
+             * .why = enables getting unique key from any ref type
+             *
+             * .note = set to null if resource lacks primary keys
+             */
+            byUnique: null | ((input: Ref<TResourceClass>, context: TContext) => Promise<RefByUnique<TResourceClass>>);
+        };
     };
+    /**
+     * .what = write operations for mutating resources
+     * .why = provides idempotent, type-safe mutations to remote state
+     */
     set: {
         /**
-         * required - find or insert resource (idempotent create)
+         * .what = find or insert resource
+         * .why = idempotent create - returns existing if found by unique keys, otherwise creates
          */
-        finsert(input: TResource, context: TContext): Promise<HasMetadata<TResource>>;
+        finsert(input: InstanceType<TResourceClass>, context: TContext): Promise<HasMetadata<InstanceType<TResourceClass>>>;
         /**
-         * optional - create or update resource (idempotent upsert)
+         * .what = create or update resource
+         * .why = idempotent upsert - creates if not found, updates if found
+         *
+         * .note = set to null if resource does not support updates
          */
-        upsert?(input: TResource, context: TContext): Promise<HasMetadata<TResource>>;
+        upsert: null | ((input: InstanceType<TResourceClass>, context: TContext) => Promise<HasMetadata<InstanceType<TResourceClass>>>);
         /**
-         * optional - delete resource
+         * .what = delete resource
+         * .why = removes resource from remote state
+         *
+         * .note = set to null if resource does not support deletion
          */
-        delete?(input: Ref<TResourceClass>, context: TContext): Promise<void>;
+        delete: null | ((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> {
+export declare class DeclastructDao<TResourceClass extends Refable<any, any, any>, TContext> extends DomainLiteral<DeclastructDao<TResourceClass, TContext>> implements DeclastructDao<TResourceClass, TContext> {
 }

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

@@ -1 +1 @@
-{"version":3,"file":"DeclastructDao.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructDao.ts"],"names":[],"mappings":";;;AAAA,mDAOwB;AAmExB,MAAa,cAKX,SAAQ,8BAAkE;CACT;AANnE,wCAMmE"}
+{"version":3,"file":"DeclastructDao.js","sourceRoot":"","sources":["../../src/domain.objects/DeclastructDao.ts"],"names":[],"mappings":";;;AAAA,mDAMwB;AA0IxB,MAAa,cAIX,SAAQ,8BAAuD;CACT;AALxD,wCAKwD"}

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

@@ -1,6 +1,6 @@
 import { DomainLiteral } from 'domain-objects';
 import type { DeclastructDao } from './DeclastructDao';
-export type DeclastructDaosShape<TContext> = Record<string, DeclastructDao<any, any, TContext>>;
+export type DeclastructDaosShape<TContext> = Record<string, DeclastructDao<any, TContext>>;
 /**
  * .what = bundles all DAOs and lifecycle hooks for a specific infrastructure provider
  * .why = enables plug-and-play support for different infrastructure backends (AWS, GCP, Azure, etc)

package/dist/domain.operations/plan/getDaoByResource.d.ts

@@ -10,6 +10,6 @@ export declare const getDaoByResource: ({ resource, providers, }: {
     resource: DomainEntity<any>;
     providers: DeclastructProvider<any, any>[];
 }) => {
-    dao: DeclastructDao<DomainEntity<any>, any, any>;
+    dao: DeclastructDao<any, any>;
     context: any;
 };

package/dist/domain.operations/plan/planChanges.js

@@ -37,7 +37,7 @@ const planChanges = async (input, context) => {
             // fetch current remote state using provider context with spinner
             const { result: remoteState, durationMs } = await (0, withSpinner_1.withSpinner)({
                 message: 'inflight',
-                operation: () => dao.get.byUnique(resource, providerContext),
+                operation: () => dao.get.one.byUnique(resource, providerContext),
             });
             // log done (replaces spinner)
             const durationSec = (durationMs / 1000).toFixed(2);

package/dist/domain.operations/plan/planChanges.js.map

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

package/dist/domain.operations/ref/getRefByPrimary.d.ts

@@ -0,0 +1,12 @@
+import { type Ref, type Refable, type RefByPrimary } from 'domain-objects';
+import type { DeclastructDao } from '../../domain.objects/DeclastructDao';
+/**
+ * .what = resolves any ref to RefByPrimary
+ * .why = enables getting primary key from any ref type
+ * .note = if ref is already RefByPrimary, returns as-is without db call
+ */
+export declare const getRefByPrimary: <TResourceClass extends Refable<any, any, any>, TContext extends Record<string, any>>(input: {
+    ref: Ref<TResourceClass>;
+}, context: {
+    dao: DeclastructDao<TResourceClass, TContext>;
+} & TContext) => Promise<RefByPrimary<TResourceClass>>;

package/dist/domain.operations/ref/getRefByPrimary.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRefByPrimary = void 0;
+const domain_objects_1 = require("domain-objects");
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = resolves any ref to RefByPrimary
+ * .why = enables getting primary key from any ref type
+ * .note = if ref is already RefByPrimary, returns as-is without db call
+ */
+const getRefByPrimary = async (input, context) => {
+    // if already RefByPrimary, return as-is without db call
+    if ((0, domain_objects_1.isRefByPrimary)({ of: context.dao.dobj })(input.ref))
+        return input.ref;
+    // if RefByUnique, fetch resource and extract primary key
+    if ((0, domain_objects_1.isRefByUnique)({ of: context.dao.dobj })(input.ref)) {
+        // fetch the resource by unique key
+        const resource = await context.dao.get.one.byUnique(input.ref, context);
+        // throw if resource not found
+        if (!resource)
+            throw new helpful_errors_1.BadRequestError('resource not found by unique ref', {
+                ref: input.ref,
+            });
+        // extract primary key from the resource
+        return (0, domain_objects_1.refByPrimary)(resource);
+    }
+    // otherwise, unexpected ref type
+    throw new helpful_errors_1.UnexpectedCodePathError('invalid ref type', { ref: input.ref });
+};
+exports.getRefByPrimary = getRefByPrimary;
+//# sourceMappingURL=getRefByPrimary.js.map

package/dist/domain.operations/ref/getRefByPrimary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRefByPrimary.js","sourceRoot":"","sources":["../../../src/domain.operations/ref/getRefByPrimary.ts"],"names":[],"mappings":";;;AAAA,mDAOwB;AACxB,mDAA0E;AAI1E;;;;GAIG;AACI,MAAM,eAAe,GAAG,KAAK,EAIlC,KAEC,EACD,OAEY,EAC2B,EAAE;IACzC,wDAAwD;IACxD,IAAI,IAAA,+BAAc,EAAC,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC;IAE1E,yDAAyD;IACzD,IAAI,IAAA,8BAAa,EAAC,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACvD,mCAAmC;QACnC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAExE,8BAA8B;QAC9B,IAAI,CAAC,QAAQ;YACX,MAAM,IAAI,gCAAe,CAAC,kCAAkC,EAAE;gBAC5D,GAAG,EAAE,KAAK,CAAC,GAAG;aACf,CAAC,CAAC;QAEL,wCAAwC;QACxC,OAAO,IAAA,6BAAY,EAAiB,QAAQ,CAAC,CAAC;IAChD,CAAC;IAED,iCAAiC;IACjC,MAAM,IAAI,wCAAuB,CAAC,kBAAkB,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;AAC5E,CAAC,CAAC;AA/BW,QAAA,eAAe,mBA+B1B"}

package/dist/domain.operations/ref/getRefByUnique.d.ts

@@ -0,0 +1,12 @@
+import { type Ref, type Refable, type RefByUnique } from 'domain-objects';
+import type { DeclastructDao } from '../../domain.objects/DeclastructDao';
+/**
+ * .what = resolves any ref to RefByUnique
+ * .why = enables getting unique key from any ref type
+ * .note = if ref is already RefByUnique, returns as-is without db call
+ */
+export declare const getRefByUnique: <TResourceClass extends Refable<any, any, any>, TContext extends Record<string, any>>(input: {
+    ref: Ref<TResourceClass>;
+}, context: {
+    dao: DeclastructDao<TResourceClass, TContext>;
+} & TContext) => Promise<RefByUnique<TResourceClass>>;

package/dist/domain.operations/ref/getRefByUnique.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRefByUnique = void 0;
+const domain_objects_1 = require("domain-objects");
+const helpful_errors_1 = require("helpful-errors");
+/**
+ * .what = resolves any ref to RefByUnique
+ * .why = enables getting unique key from any ref type
+ * .note = if ref is already RefByUnique, returns as-is without db call
+ */
+const getRefByUnique = async (input, context) => {
+    // if already RefByUnique, return as-is without db call
+    if ((0, domain_objects_1.isRefByUnique)({ of: context.dao.dobj })(input.ref))
+        return input.ref;
+    // if RefByPrimary, fetch resource and extract unique key
+    if ((0, domain_objects_1.isRefByPrimary)({ of: context.dao.dobj })(input.ref)) {
+        // verify dao supports byPrimary
+        if (!context.dao.get.one.byPrimary)
+            throw new helpful_errors_1.UnexpectedCodePathError('dao does not support byPrimary lookup', { ref: input.ref });
+        // fetch the resource by primary key
+        const resource = await context.dao.get.one.byPrimary(input.ref, context);
+        // throw if resource not found
+        if (!resource)
+            throw new helpful_errors_1.BadRequestError('resource not found by primary ref', {
+                ref: input.ref,
+            });
+        // extract unique key from the resource
+        return (0, domain_objects_1.refByUnique)(resource);
+    }
+    // otherwise, unexpected ref type
+    throw new helpful_errors_1.UnexpectedCodePathError('invalid ref type', { ref: input.ref });
+};
+exports.getRefByUnique = getRefByUnique;
+//# sourceMappingURL=getRefByUnique.js.map

package/dist/domain.operations/ref/getRefByUnique.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRefByUnique.js","sourceRoot":"","sources":["../../../src/domain.operations/ref/getRefByUnique.ts"],"names":[],"mappings":";;;AAAA,mDAOwB;AACxB,mDAA0E;AAI1E;;;;GAIG;AACI,MAAM,cAAc,GAAG,KAAK,EAIjC,KAEC,EACD,OAEY,EAC0B,EAAE;IACxC,uDAAuD;IACvD,IAAI,IAAA,8BAAa,EAAC,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC;IAEzE,yDAAyD;IACzD,IAAI,IAAA,+BAAc,EAAC,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACxD,gCAAgC;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS;YAChC,MAAM,IAAI,wCAAuB,CAC/B,uCAAuC,EACvC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CACnB,CAAC;QAEJ,oCAAoC;QACpC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAEzE,8BAA8B;QAC9B,IAAI,CAAC,QAAQ;YACX,MAAM,IAAI,gCAAe,CAAC,mCAAmC,EAAE;gBAC7D,GAAG,EAAE,KAAK,CAAC,GAAG;aACf,CAAC,CAAC;QAEL,uCAAuC;QACvC,OAAO,IAAA,4BAAW,EAAiB,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,iCAAiC;IACjC,MAAM,IAAI,wCAAuB,CAAC,kBAAkB,EAAE,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;AAC5E,CAAC,CAAC;AAtCW,QAAA,cAAc,kBAsCzB"}

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.4.5",
+  "version": "1.5.1",
   "repository": "ehmpathy/declastruct",
   "homepage": "https://github.com/ehmpathy/declastruct",
   "keywords": [
@@ -87,8 +87,8 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.12.1",
-    "rhachet-roles-ehmpathy": "1.9.1",
+    "rhachet": "1.12.3",
+    "rhachet-roles-ehmpathy": "1.12.0",
     "test-fns": "1.7.2",
     "tsx": "4.20.6",
     "typescript": "5.4.5"