declastruct 1.5.2 → 1.6.0

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

@@ -4,6 +4,8 @@ export { DeclastructChange, DeclastructChangeAction, } from '../../domain.object
 export { DeclastructDao } from '../../domain.objects/DeclastructDao';
 export { DeclastructPlan } from '../../domain.objects/DeclastructPlan';
 export { DeclastructProvider } from '../../domain.objects/DeclastructProvider';
+export type { DeclastructDaoInput, DeclastructDaoWithRef, DeclastructDaoWoutRef, } from '../../domain.objects/genDeclastructDao';
+export { genDeclastructDao } from '../../domain.objects/genDeclastructDao';
 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.getRefByUnique = exports.getRefByPrimary = exports.DeclastructProvider = exports.DeclastructPlan = exports.DeclastructDao = exports.DeclastructChangeAction = exports.DeclastructChange = void 0;
+exports.getRefByUnique = exports.getRefByPrimary = exports.genDeclastructDao = 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,6 +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; } });
+// factories
+var genDeclastructDao_1 = require("../../domain.objects/genDeclastructDao");
+Object.defineProperty(exports, "genDeclastructDao", { enumerable: true, get: function () { return genDeclastructDao_1.genDeclastructDao; } });
 // domain operations
 var getRefByPrimary_1 = require("../../domain.operations/ref/getRefByPrimary");
 Object.defineProperty(exports, "getRefByPrimary", { enumerable: true, get: function () { return getRefByPrimary_1.getRefByPrimary; } });

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;;;AAIjB,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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contract/sdk/index.ts"],"names":[],"mappings":";AAAA,iBAAiB;;;AAIjB,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;AAM5B,YAAY;AACZ,4EAA2E;AAAlE,sHAAA,iBAAiB,OAAA;AAE1B,oBAAoB;AACpB,+EAA8E;AAArE,kHAAA,eAAe,OAAA;AACxB,6EAA4E;AAAnE,gHAAA,cAAc,OAAA"}

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

@@ -56,14 +56,14 @@ export interface DeclastructDao<TResourceClass extends Refable<any, any, any>, T
              *
              * .note = set to null if resource lacks primary keys
              */
-            byPrimary: null | ((input: Ref<TResourceClass>, context: TContext) => Promise<RefByPrimary<TResourceClass>>);
+            byPrimary: null | ((input: Ref<TResourceClass>, context: TContext) => Promise<RefByPrimary<TResourceClass> | null>);
             /**
              * .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>>);
+            byUnique: null | ((input: Ref<TResourceClass>, context: TContext) => Promise<RefByUnique<TResourceClass> | null>);
         };
     };
     /**

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

@@ -0,0 +1,71 @@
+import { type Ref, type Refable, type RefByPrimary, type RefByUnique } from 'domain-objects';
+import type { DeclastructDao } from './DeclastructDao';
+/**
+ * .what = input type for genDeclastructDao without get.ref and get.one.byRef (auto-wired by factory)
+ * .why = derives from DeclastructDao to stay in sync, omits auto-wired methods
+ */
+export type DeclastructDaoInput<TResourceClass extends Refable<any, any, any>, TContext> = Omit<DeclastructDao<TResourceClass, TContext>, 'get'> & {
+    get: {
+        one: Omit<DeclastructDao<TResourceClass, TContext>['get']['one'], 'byRef'>;
+    };
+};
+/**
+ * .what = input type for daos with byPrimary defined
+ * .why = enables overload to distinguish daos with primary key support
+ */
+export type DeclastructDaoInputWithPrimary<TResourceClass extends Refable<any, any, any>, TContext> = Omit<DeclastructDaoInput<TResourceClass, TContext>, 'get'> & {
+    get: {
+        one: Omit<DeclastructDao<TResourceClass, TContext>['get']['one'], 'byPrimary' | 'byRef'> & {
+            byPrimary: NonNullable<DeclastructDao<TResourceClass, TContext>['get']['one']['byPrimary']>;
+        };
+    };
+};
+/**
+ * .what = input type for daos without byPrimary
+ * .why = enables overload to distinguish daos without primary key support
+ */
+export type DeclastructDaoInputWoutPrimary<TResourceClass extends Refable<any, any, any>, TContext> = Omit<DeclastructDaoInput<TResourceClass, TContext>, 'get'> & {
+    get: {
+        one: Omit<DeclastructDao<TResourceClass, TContext>['get']['one'], 'byPrimary' | 'byRef'> & {
+            byPrimary: null;
+        };
+    };
+};
+/**
+ * .what = output type for daos with ref methods defined
+ * .why = enables type-safe access to ref resolution methods
+ */
+export type DeclastructDaoWithRef<TResourceClass extends Refable<any, any, any>, TContext> = Omit<DeclastructDao<TResourceClass, TContext>, 'get'> & {
+    get: {
+        one: DeclastructDao<TResourceClass, TContext>['get']['one'];
+        ref: {
+            byPrimary: (input: Ref<TResourceClass>, context: TContext) => Promise<RefByPrimary<TResourceClass> | null>;
+            byUnique: (input: Ref<TResourceClass>, context: TContext) => Promise<RefByUnique<TResourceClass> | null>;
+        };
+    };
+};
+/**
+ * .what = output type for daos without ref methods
+ * .why = forces explicit null for ref methods when byPrimary is not supported
+ */
+export type DeclastructDaoWoutRef<TResourceClass extends Refable<any, any, any>, TContext> = Omit<DeclastructDao<TResourceClass, TContext>, 'get'> & {
+    get: {
+        one: DeclastructDao<TResourceClass, TContext>['get']['one'];
+        ref: {
+            byPrimary: null;
+            byUnique: null;
+        };
+    };
+};
+/**
+ * .what = factory to create DeclastructDao with auto-wired ref methods
+ * .why = enforces that ref methods are defined iff byPrimary is defined
+ * .note = TContext must be explicitly provided as a generic parameter to avoid hazardous Record<string, any> inference
+ *
+ * @overload input with byPrimary defined → output with ref methods defined
+ */
+export declare function genDeclastructDao<TResourceClass extends Refable<any, any, any>, TContext extends Record<string, any> = never>(input: DeclastructDaoInputWithPrimary<TResourceClass, TContext>): DeclastructDaoWithRef<TResourceClass, TContext>;
+/**
+ * @overload input without byPrimary → output with ref methods null
+ */
+export declare function genDeclastructDao<TResourceClass extends Refable<any, any, any>, TContext extends Record<string, any> = never>(input: DeclastructDaoInputWoutPrimary<TResourceClass, TContext>): DeclastructDaoWoutRef<TResourceClass, TContext>;

package/dist/domain.objects/genDeclastructDao.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.genDeclastructDao = void 0;
+const domain_objects_1 = require("domain-objects");
+const helpful_errors_1 = require("helpful-errors");
+const getRefByPrimary_1 = require("../domain.operations/ref/getRefByPrimary");
+const getRefByUnique_1 = require("../domain.operations/ref/getRefByUnique");
+/**
+ * .impl = creates dao with byRef and ref methods auto-wired based on byPrimary presence
+ */
+function genDeclastructDao(input) {
+    const hasPrimary = input.get.one.byPrimary !== null;
+    // build byRef from byUnique + byPrimary
+    const byRef = async (ref, context) => {
+        if ((0, domain_objects_1.isRefByPrimary)({ of: input.dobj })(ref) && input.get.one.byPrimary)
+            return input.get.one.byPrimary(ref, context);
+        if ((0, domain_objects_1.isRefByUnique)({ of: input.dobj })(ref))
+            return input.get.one.byUnique(ref, context);
+        throw new helpful_errors_1.BadRequestError('get.one.byRef called with neither a RefByUnique nor RefByPrimary', { ref });
+    };
+    if (hasPrimary) {
+        // auto-wire ref methods using the helper functions
+        const dao = {
+            ...input,
+            get: {
+                one: {
+                    ...input.get.one,
+                    byRef,
+                },
+                ref: {
+                    byPrimary: (ref, context) => (0, getRefByPrimary_1.getRefByPrimary)({ ref }, { dao, ...context }),
+                    byUnique: (ref, context) => (0, getRefByUnique_1.getRefByUnique)({ ref }, { dao, ...context }),
+                },
+            },
+        };
+        return dao;
+    }
+    // no primary key support - ref methods are null
+    return {
+        ...input,
+        get: {
+            one: {
+                ...input.get.one,
+                byRef,
+            },
+            ref: {
+                byPrimary: null,
+                byUnique: null,
+            },
+        },
+    };
+}
+exports.genDeclastructDao = genDeclastructDao;
+//# sourceMappingURL=genDeclastructDao.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"genDeclastructDao.js","sourceRoot":"","sources":["../../src/domain.objects/genDeclastructDao.ts"],"names":[],"mappings":";;;AAAA,mDAOwB;AACxB,mDAAiD;AAEjD,8EAA2E;AAC3E,4EAAyE;AAwHzE;;GAEG;AACH,SAAgB,iBAAiB,CAI/B,KAAoD;IAEpD,MAAM,UAAU,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,KAAK,IAAI,CAAC;IAEpD,wCAAwC;IACxC,MAAM,KAAK,GAAG,KAAK,EACjB,GAAwB,EACxB,OAAiB,EAC6B,EAAE;QAChD,IAAI,IAAA,+BAAc,EAAC,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS;YACpE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/C,IAAI,IAAA,8BAAa,EAAC,EAAE,EAAE,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC;YACxC,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC9C,MAAM,IAAI,gCAAe,CACvB,kEAAkE,EAClE,EAAE,GAAG,EAAE,CACR,CAAC;IACJ,CAAC,CAAC;IAEF,IAAI,UAAU,EAAE,CAAC;QACf,mDAAmD;QACnD,MAAM,GAAG,GAA6C;YACpD,GAAG,KAAK;YACR,GAAG,EAAE;gBACH,GAAG,EAAE;oBACH,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG;oBAChB,KAAK;iBACN;gBACD,GAAG,EAAE;oBACH,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAC1B,IAAA,iCAAe,EAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;oBAC/C,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CACzB,IAAA,+BAAc,EAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;iBAC/C;aACF;SACF,CAAC;QACF,OAAO,GAAG,CAAC;IACb,CAAC;IAED,gDAAgD;IAChD,OAAO;QACL,GAAG,KAAK;QACR,GAAG,EAAE;YACH,GAAG,EAAE;gBACH,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG;gBAChB,KAAK;aACN;YACD,GAAG,EAAE;gBACH,SAAS,EAAE,IAAI;gBACf,QAAQ,EAAE,IAAI;aACf;SACF;KACF,CAAC;AACJ,CAAC;AAzDD,8CAyDC"}

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

@@ -9,4 +9,4 @@ export declare const getRefByPrimary: <TResourceClass extends Refable<any, any,
     ref: Ref<TResourceClass>;
 }, context: {
     dao: DeclastructDao<TResourceClass, TContext>;
-} & TContext) => Promise<RefByPrimary<TResourceClass>>;
+} & TContext) => Promise<RefByPrimary<TResourceClass> | null>;

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

@@ -16,11 +16,9 @@ const getRefByPrimary = async (input, context) => {
     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
+        // return null if resource not found (resource may not exist yet)
         if (!resource)
-            throw new helpful_errors_1.BadRequestError('resource not found by unique ref', {
-                ref: input.ref,
-            });
+            return null;
         // extract primary key from the resource
         return (0, domain_objects_1.refByPrimary)(resource);
     }

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

@@ -1 +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"}
+{"version":3,"file":"getRefByPrimary.js","sourceRoot":"","sources":["../../../src/domain.operations/ref/getRefByPrimary.ts"],"names":[],"mappings":";;;AAAA,mDAOwB;AACxB,mDAAyD;AAIzD;;;;GAIG;AACI,MAAM,eAAe,GAAG,KAAK,EAIlC,KAEC,EACD,OAEY,EACkC,EAAE;IAChD,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,iEAAiE;QACjE,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAE3B,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;AA5BW,QAAA,eAAe,mBA4B1B"}

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

@@ -9,4 +9,4 @@ export declare const getRefByUnique: <TResourceClass extends Refable<any, any, a
     ref: Ref<TResourceClass>;
 }, context: {
     dao: DeclastructDao<TResourceClass, TContext>;
-} & TContext) => Promise<RefByUnique<TResourceClass>>;
+} & TContext) => Promise<RefByUnique<TResourceClass> | null>;

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

@@ -19,11 +19,9 @@ const getRefByUnique = async (input, context) => {
             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
+        // return null if resource not found (resource may not exist yet)
         if (!resource)
-            throw new helpful_errors_1.BadRequestError('resource not found by primary ref', {
-                ref: input.ref,
-            });
+            return null;
         // extract unique key from the resource
         return (0, domain_objects_1.refByUnique)(resource);
     }

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

@@ -1 +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"}
+{"version":3,"file":"getRefByUnique.js","sourceRoot":"","sources":["../../../src/domain.operations/ref/getRefByUnique.ts"],"names":[],"mappings":";;;AAAA,mDAOwB;AACxB,mDAAyD;AAIzD;;;;GAIG;AACI,MAAM,cAAc,GAAG,KAAK,EAIjC,KAEC,EACD,OAEY,EACiC,EAAE;IAC/C,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,iEAAiE;QACjE,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QAE3B,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;AAnCW,QAAA,cAAc,kBAmCzB"}

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.5.2",
+  "version": "1.6.0",
   "repository": "ehmpathy/declastruct",
   "homepage": "https://github.com/ehmpathy/declastruct",
   "keywords": [

package/readme.md

@@ -270,3 +270,145 @@ each `DeclastructChange` includes:
 ## inspiration
 
 inspired by Terraform's declarative approach, but designed to eliminate state file overhead, work with any resource construct, be reusable across both prod codepaths and cicd control, and leverage TypeScript's type system for safer declarative instructions.
+
+
+# plugin
+
+build your own provider to control any resource construct via declastruct.
+
+## 1. declare your resource
+
+define your resource as a [`domain-object`](https://github.com/ehmpathy/domain-objects) with key attributes:
+
+```ts
+import { DomainEntity } from 'domain-objects';
+
+interface DeclaredStripeCustomer {
+  id?: string;
+  email: string;
+  name: string;
+  status?: string;
+}
+class DeclaredStripeCustomer
+  extends DomainEntity<DeclaredStripeCustomer>
+  implements DeclaredStripeCustomer
+{
+  // primary key: the surrogate key identifier for this resource
+  public static primary = ['id'] as const;
+
+  // unique key: the natural key identifier for this resource (i.e., the non-primary unique key)
+  public static unique = ['email'] as const;
+
+  // metadata keys: readonly persistance-specific fields - excluded from change detection
+  // if unspecified, the defaults of 'id', 'uuid', 'createdAt', 'updatedAt', 'effectiveAt' will be assumed
+  public static metadata = ['id'] as const;
+
+  // readonly keys: readonly domain-intrinsic fields - excluded from change detection
+  // note: all metadata is implicitly readonly, so you only need to specify non-metadata readonly keys here
+  public static readonly = ['status'] as const;
+}
+```
+
+key attributes to consider:
+- **primary key** (`static primary`): surrogate identifier for efficient lookups after creation
+- **unique key** (`static unique`): natural key that uniquely identifies the resource, used for idempotent operations
+- **metadata keys** (`static metadata`): readonly persistence-layer fields that describe *how* the object is stored (e.g., `uuid`, `createdAt`). note, metadata is a specific subset of readonly
+- **readonly keys** (`static readonly`): readonly domain-layer fields that describe *what* the object is (e.g., `status`). note, you only need to declare the readonly attributes that are not already flagged as metadata here
+
+## 2. generate your dao
+
+use `genDeclastructDao` to create a type-safe DAO with auto-wired ref resolution:
+
+```ts
+import { genDeclastructDao } from 'declastruct';
+import Stripe from 'stripe';
+
+// define the context type for your provider
+interface StripeContext {
+  stripe: Stripe;
+}
+
+const daoStripeCustomer = genDeclastructDao<
+  typeof DeclaredStripeCustomer,
+  StripeContext
+>({
+  dobj: DeclaredStripeCustomer,
+  get: {
+    one: {
+      byUnique: async ({ email }, context) => {
+        // lookup by natural key (email)
+        const customer = await context.stripe.customers.list({ email });
+        return customer.data[0] ? toResource(customer.data[0]) : null;
+      },
+      byPrimary: async ({ id }, context) => {
+        // lookup by stripe-assigned id
+        const customer = await context.stripe.customers.retrieve(id);
+        return customer ? toResource(customer) : null;
+      },
+    },
+  },
+  set: {
+    finsert: async (resource, context) => {
+      // find-or-insert: idempotent create
+      const foundBefore = await daoStripeCustomer.get.one.byUnique(
+        { email: resource.email },
+        context,
+      );
+      if (foundBefore) return foundBefore;
+
+      const created = await context.stripe.customers.create({
+        email: resource.email,
+        name: resource.name,
+      });
+      return toResource(created);
+    },
+    upsert: async (resource, context) => {
+      // update-or-insert: idempotent update
+      const foundBefore = await daoStripeCustomer.get.one.byUnique(
+        { email: resource.email },
+        context,
+      );
+      if (foundBefore) {
+        const updated = await context.stripe.customers.update(foundBefore.id, {
+          name: resource.name,
+        });
+        return toResource(updated);
+      }
+      return daoStripeCustomer.set.finsert(resource, context);
+    },
+    delete: async (ref, context) => {
+      const foundBefore = await daoStripeCustomer.get.one.byRef(ref, context);
+      if (foundBefore) await context.stripe.customers.del(foundBefore.id);
+    },
+  },
+});
+```
+
+the factory automatically:
+- **builds get.one.byRef**: `get.one.byRef` is built for you, based on `get.one.byUnique` and `get.one.byPrimary`
+- **builds get.ref.byPrimary,.byUnique**: if `byPrimary` is defined, `get.ref.byPrimary` and `get.ref.byUnique` are built for you, based on `get.one.byUnique` and `get.one.byPrimary`
+- **enforces type safety**: if `byPrimary` is null, `get.ref.*` are typed as null (prevents accidental calls)
+
+## 3. create your provider
+
+bundle your DAOs into a provider:
+
+```ts
+import { DeclastructProvider } from 'declastruct';
+
+export const stripeProvider = new DeclastructProvider({
+  name: 'stripe',
+  daos: {
+    DeclaredStripeCustomer: daoStripeCustomer,
+  },
+  context: {
+    stripe,  // stripe client instance
+  },
+  hooks: {
+    beforeAll: async () => { /* setup */ },
+    afterAll: async () => { /* cleanup */ },
+  },
+});
+```
+
+now users can declare stripe customers and use `plan` + `apply` to control them declaratively.