@sanoma-ai/workflows 0.9.1 → 0.10.0

package/src/resource.ts

@@ -1,3 +1,4 @@
+import type { ConnectionRef } from "./connection.ts";
 import { z } from "zod";
 import { checkDatabase, type DatabaseSpec } from "./database.ts";
 import { isRunControlError } from "./errors.ts";
@@ -173,7 +174,7 @@ export async function callAfterCreate(
  */
 export const DECLARED: unique symbol = Symbol.for("sanoma.declared");
 
-/** A resource a data file declares: `github.repository({ name: "sanoma" })`. */
+/** A resource a data file declares: `github.repository({ owner: "acme", name: "sanoma" })`. */
 export interface Declared<Id extends string = string, T = State> {
   readonly [DECLARED]: Id;
   readonly vendor: string;
@@ -185,6 +186,7 @@ export interface Declared<Id extends string = string, T = State> {
    * checked, and what a drift check compares.
    */
   readonly desired: T;
+  readonly connection?: ConnectionRef;
   /**
    * Where it names another resource: the field's dotted path (a list item's with its index,
    * `teams.0`) to that resource's `<vendor>.<type>:<name>`.
@@ -331,7 +333,10 @@ export interface Resource<
       >
     >,
     Readonly<Pick<ResourceSpec<S>, "identity" | "find" | "host" | "wakeup" | "database" | "afterCreate">> {
-  (desired: Declaring<z.input<S>, R>): Declared<Id, z.input<S>>;
+  (
+    desired: Declaring<z.input<S>, R>,
+    options?: { connection?: ConnectionRef<Id extends `${infer V}.${string}` ? V : string> },
+  ): Declared<Id, z.input<S>>;
   /** `read` and `import`, each effect `read`, idempotent, with the id as `target`; for a writable type, the change operations too. */
   readonly ops: ResourceOps<S, W>;
   /** True when apply may change its objects: it has the change operations. */
@@ -349,7 +354,9 @@ export const isObject = (v: unknown): v is State => typeof v === "object" && v !
 /** `path.name`, or `name` at the top: a field's dotted path. */
 export const joinPath = (path: string, name: string) => (path ? `${path}.${name}` : name);
 
-const isDeclared = (v: unknown): v is Declared => isObject(v) && typeof (v as Partial<Declared>)[DECLARED] === "string";
+/** A declared resource: what a constructor returns, made by any copy of this package. */
+export const isDeclared = (v: unknown): v is Declared =>
+  isObject(v) && typeof (v as Partial<Declared>)[DECLARED] === "string";
 
 /** One order for a list compared as a multiset: by each item's JSON. */
 const canonical = (items: unknown[]) =>
@@ -577,8 +584,8 @@ function pathsIn(value: unknown, paths: ReadonlySet<string>, prefix = ""): strin
  *
  * The ledger records a `handle` as `"<handle>"`, never its bytes (the operations' `opaque`).
  *
- * Calling the result declares one resource, for a data file: `repository({ name: "sanoma" })`
- * is a `Declared`, `{ vendor, type, name: "sanoma", desired, refs: {} }`. It refuses fields the
+ * Calling the result declares one resource, for a data file: `repository({ owner: "acme", name: "sanoma" })`
+ * is a `Declared`, `{ vendor, type, name: "acme/sanoma", desired, refs: {} }`. It refuses fields the
  * schema does not have, fields the vendor owns (unless the identity names them), values the
  * schema rejects, and an empty identity. Where `fields.references` allows it, a field may name
  * another declared resource of that type (`repository_id: site`): `desired` holds, and the
@@ -663,7 +670,17 @@ export function defineResource<
   const owned = new Set(fields.vendorOwned.filter((path) => !named.has(path)));
   const references: References = fields.references ?? {};
   const writeOnly = new Set(fields.writeOnly);
-  const declare = (given: Declaring<z.input<S>, R>): Declared<`${V}.${T}`, z.input<S>> => {
+  const declare = (
+    given: Declaring<z.input<S>, R>,
+    options?: { connection?: ConnectionRef },
+  ): Declared<`${V}.${T}`, z.input<S>> => {
+    const connection = options?.connection;
+    if (
+      connection &&
+      (connection.vendor !== vendor || !new RegExp(`^${vendor}/[a-z][a-z0-9-]{0,63}$`).test(connection.$connection))
+    ) {
+      throw new Error(`${what}: select a declared connection of this connector`);
+    }
     const refs: Record<string, string> = {};
     // Where a secret is given, with list items' indexes: the schema does not judge its marker.
     const secrets = new Set<string>();
@@ -723,6 +740,7 @@ export function defineResource<
       ...(name !== undefined && { name }),
       desired,
       refs: Object.freeze(refs),
+      ...(connection && { connection: Object.freeze({ ...connection }) }),
     });
   };
   const resource = Object.assign(declare, {