@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/framework/overlay.d.ts

@@ -0,0 +1,49 @@
+import { ConfigIssueCode } from "./rejection.js";
+import { Patch } from "./Config.js";
+
+//#region src/framework/overlay.d.ts
+/** A pending patch plus the id that lets a caller correlate it — with an optimistic UI gesture now,
+ *  and with its `draft_patches` row — and the changeset it belongs to, when it is one of several. */
+interface StampedPatch {
+  readonly id: string;
+  readonly patch: Patch;
+  /** The schema version the WRITER was on — what replay hands `upgradePatch` after a bump. Absent
+   *  means 1: a patch stored before versioning existed. */
+  readonly schemaVersion?: number;
+  /**
+   * The changeset this patch belongs to — the set of patches one gesture wrote, named by the id the
+   * caller staged for the gesture, which is also its first patch's. A custom op that decomposes into
+   * several patches, a multi-op call, a copy of a linked system: each is one thing a person did, and
+   * the rows it wrote carry the same changeset so a list shows one line, undo drops one step, and a
+   * replay keeps or drops the gesture whole. A single patch carries none. Nothing but the id: what a
+   * changeset is called is derived from its rows where it is shown.
+   */
+  readonly changeset?: string;
+}
+/** A patch that could not be replayed onto a new base, and the reason — reported rather than
+ *  swallowed, so a surface can tell the user which of their edits the remote change invalidated. */
+interface RebaseConflict {
+  readonly id: string;
+  readonly patch: Patch;
+  /** The error `apply` threw — "No component at "Button"", a validation failure, … */
+  readonly reason: string;
+  /**
+   * The rejection's own category (`NOT_FOUND`, `ALREADY_EXISTS`, …), or `INTERNAL` when the throw
+   * wasn't a `ConfigRejection` — an environmental failure (an unresolved linked source, a malformed
+   * pre-cutover row) rather than a refused write. A surface words the two differently: a refusal is
+   * about the user's edit, an internal error is not.
+   */
+  readonly code: ConfigIssueCode | 'INTERNAL';
+}
+/** What `rebase` hands back: the replayed config, and the edits that didn't survive. Generic in the
+ *  config type so `rebase` can return the receiver's own type (a `this` type can't be written inline
+ *  in an object literal). */
+interface RebaseResult<C> {
+  readonly config: C;
+  readonly dropped: RebaseConflict[];
+}
+/** Stamp a patch for the pending log. Ids must be unique across CLIENTS (they become the durable
+ *  log's `client_patch_id`), so this is a uuid rather than a counter; tests pass their own. */
+declare function stamp(patch: Patch, id?: string, changeset?: string): StampedPatch;
+//#endregion
+export { RebaseConflict, RebaseResult, StampedPatch, stamp };

package/dist/framework/overlay.js

@@ -0,0 +1,17 @@
+import { CURRENT_SCHEMA_VERSION } from "./schema-version.js";
+//#region src/framework/overlay.ts
+/** Stamp a patch for the pending log. Ids must be unique across CLIENTS (they become the durable
+*  log's `client_patch_id`), so this is a uuid rather than a counter; tests pass their own. */
+function stamp(patch, id = crypto.randomUUID(), changeset) {
+	const stamped = {
+		id,
+		patch,
+		schemaVersion: CURRENT_SCHEMA_VERSION
+	};
+	return changeset ? {
+		...stamped,
+		changeset
+	} : stamped;
+}
+//#endregion
+export { stamp };

package/dist/framework/plan.d.ts

@@ -0,0 +1,49 @@
+import { ConfigOp } from "./config-op.js";
+import { StampedPatch } from "./overlay.js";
+import { Patch } from "./Config.js";
+
+//#region src/framework/plan.d.ts
+type PlanOp = ConfigOp;
+/** What a kind's own `<verb>-plan` read says about one op in the plan. */
+interface PlanImpact {
+  /** The op the account is about, `token/rename`. */
+  readonly op: string;
+  /** The read's answer: a `RenamePlan`, a `DeletePlan`, a `LinkPlan`, whatever the kind declared. */
+  readonly answer: unknown;
+}
+interface Plan {
+  /** The patches the ops would append, in order, stamped as `run` would stamp them. */
+  readonly patches: readonly StampedPatch[];
+  /** One line per patch, from {@link describePatch}. */
+  readonly summaries: readonly string[];
+  /** The kinds' own accounts of the ops that have one, in op order. */
+  readonly impact: readonly PlanImpact[];
+}
+/** An entity by kind and path. */
+interface EntityAddress {
+  readonly kind: string;
+  readonly path: string;
+}
+interface RenamePlan {
+  readonly from: string;
+  readonly to: string;
+  /** Every entity the cascade rewrites: a body holding a ref to the old path, or its name as a key. */
+  readonly rewrites: readonly EntityAddress[];
+  /** Why the rename would be refused. `undefined` when it would go through. */
+  readonly blocked?: string;
+}
+interface DeletePlan {
+  readonly path: string;
+  /** What still points at the entity. Each has to move or go before the delete is allowed. */
+  readonly dependents: readonly EntityAddress[];
+  /** Why the delete would be refused. `undefined` when it would go through. */
+  readonly blocked?: string;
+}
+/**
+ * One line for a patch, read off the patch itself: its kind, what it did, and where. The payload
+ * already names all three, so a kind declared in userland describes itself with no case here. An
+ * operation has the same shape, so a receipt for a batch describes its ops the same way.
+ */
+declare function describePatch(patch: Patch | ConfigOp): string;
+//#endregion
+export { DeletePlan, EntityAddress, Plan, PlanImpact, PlanOp, RenamePlan, describePatch };

package/dist/framework/plan.js

@@ -0,0 +1,73 @@
+import { isConfigRejection } from "./rejection.js";
+import { splitRef } from "./utils/refs.js";
+//#region src/framework/plan.ts
+/**
+* One line for a patch, read off the patch itself: its kind, what it did, and where. The payload
+* already names all three, so a kind declared in userland describes itself with no case here. An
+* operation has the same shape, so a receipt for a batch describes its ops the same way.
+*/
+function describePatch(patch) {
+	const { kind, operation } = patch;
+	const { path, owner, field, key, to } = patch;
+	return [
+		kind,
+		operation,
+		[
+			path,
+			owner,
+			field,
+			key
+		].filter(Boolean).join(" "),
+		to === void 0 ? void 0 : `to ${to}`
+	].filter(Boolean).join(" ");
+}
+/**
+* The refusal an op would answer with, or `undefined` when it would go through. Anything else the
+* attempt throws is not a refusal and propagates.
+*/
+function blockedBy(attempt) {
+	try {
+		attempt();
+		return;
+	} catch (error) {
+		if (isConfigRejection(error)) return error.message;
+		throw error;
+	}
+}
+function addresses(targets) {
+	return targets.map((target) => {
+		const { kind, qualifiedPath } = splitRef(target);
+		return {
+			kind,
+			path: qualifiedPath
+		};
+	});
+}
+function planRename({ config, kind, path, to }) {
+	const blocked = blockedBy(() => config.run([{
+		kind,
+		operation: "rename",
+		path,
+		to
+	}]));
+	return {
+		from: path,
+		to,
+		rewrites: addresses(config.dependentsOf(kind, path)),
+		...blocked === void 0 ? {} : { blocked }
+	};
+}
+function planDelete({ config, kind, path }) {
+	const blocked = blockedBy(() => config.run([{
+		kind,
+		operation: "delete",
+		path
+	}]));
+	return {
+		path,
+		dependents: addresses(config.dependentsOf(kind, path)),
+		...blocked === void 0 ? {} : { blocked }
+	};
+}
+//#endregion
+export { blockedBy, describePatch, planDelete, planRename };