@objectstack/types 17.0.0-rc.5 → 17.0.0-rc.6

package/dist/index.d.ts

@@ -680,6 +680,197 @@ declare function sendOk(res: EnvelopeResponse, data: unknown, status?: number):
  */
 declare function sendError(res: EnvelopeResponse, status: number, code: ErrorCode, message: string, extra?: Pick<ApiError, 'category' | 'httpStatus' | 'details' | 'requestId'>): void;
 
+/**
+ * The one home for Postgres' `«sub-object» "x" of relation "y" …` phrasing
+ * (#6615).
+ *
+ * ## The superstring hole, stated once
+ *
+ * Postgres phrases a failure about something *inside* a relation by naming the
+ * relation too:
+ *
+ * ```
+ * column     "label"           of relation "sys_team" does not exist   (42703)
+ * constraint "uq_sys_team_name" of relation "sys_team" does not exist  (42704)
+ * column     "environment_id"  of relation "sys_metadata" already exists (42701)
+ * ```
+ *
+ * Every one of those **contains a complete, legal missing-TABLE phrase** —
+ * `relation "sys_team" does not exist` — as a substring, while meaning the
+ * opposite: the relation is right there, which is precisely why it could be
+ * named. No amount of tightening a "does this say a relation is missing?"
+ * regex can remove that match, because the phrase really is in there. The only
+ * repair is to ask the more specific question FIRST. That makes the ORDER the
+ * fix, not the pattern — and it is why three packages each grew their own copy
+ * of this phrase (#5352, #6035/PR #6346, #6347/PR #6613) before it was given a
+ * home.
+ *
+ * ## Two widths, on purpose — never collapse them
+ *
+ * The three consumers do not want the same regex, and the difference is not
+ * sloppiness: it is **which direction of error is safe** at each site.
+ *
+ * | consumer | asks | uses | a MISS costs |
+ * |:---|:---|:---|:---|
+ * | `@objectstack/rest` `mapDataError` (#5352) | which column? | {@link matchMissingColumnOfRelation} | a vaguer message (`404` instead of `400 INVALID_FIELD`) |
+ * | `@objectstack/service-analytics` `isMissingSourceError` / `missingSourceRelation` (#6035) | is this a missing COLUMN, so keep it hard? | {@link matchMissingColumnOfRelation} | a mistyped column degrades to a confident empty chart |
+ * | `@objectstack/metadata` `MISSING_TABLE.excludes` (#6347) | is this about a sub-object, so not a missing table? | {@link isRelationSubObjectPhrase} | a corruption verdict returns (`event_seq` restarts at 1) |
+ *
+ * The first two **extract**, so they must be strict: over-matching there would
+ * turn a genuinely missing table into a hard failure and regress #5033's
+ * deliberate leniency, while under-matching merely keeps today's verdict. The
+ * third **excludes**, so it is deliberately wider — any sub-object, any quoted
+ * identifier, any verdict — because over-matching there only ever converts a
+ * benign verdict into a loud one, and a miss restores data corruption.
+ *
+ * Collapsing the two into one regex would therefore be wrong for one caller
+ * whichever width won. They are two exports for that reason, and the reason is
+ * load-bearing rather than stylistic.
+ *
+ * ## Home
+ *
+ * `@objectstack/types`, following `isUniqueViolationError`'s move
+ * (#6250 — four hand-written answers to one question) and
+ * `isModuleNotFoundError`'s (framework#3265 — "single shared owner … so the
+ * parallel loaders cannot drift apart"). This module deliberately imports
+ * nothing.
+ *
+ * ⚠️ Unlike #6250, adopting this **does** add one dependency edge:
+ * `@objectstack/service-analytics` did not depend on `@objectstack/types`
+ * before #6615. It is acyclic by construction — `@objectstack/types` depends
+ * only on `@objectstack/spec`, which depends on nothing in-repo, so no package
+ * except `spec` itself can form a cycle by consuming it — and 25 of the repo's
+ * 73 packages (5 of 16 services) already carry the same edge. Recorded here
+ * rather than left for a reader to rediscover.
+ */
+/**
+ * Postgres' missing-COLUMN template, strictly. Returns the column name, or
+ * `undefined` when the message is not that phrase.
+ *
+ * Anchored to `column "%s" of relation "%s" does not exist` — the exact errmsg
+ * template Postgres emits for SQLSTATE 42703 on the write path
+ * (`INSERT` / `UPDATE` / `ALTER`). Both quotes are required because Postgres
+ * always emits them here, and requiring them is the safe direction of error for
+ * the two consumers that call this.
+ *
+ * Deliberately narrow in two further ways, both preserved verbatim from the
+ * open-coded copies this replaces:
+ *
+ * - the identifier is `[a-z0-9_]+` (case-insensitive), so a quoted identifier
+ *   carrying a space or punctuation is NOT matched. Postgres can quote such
+ *   names; the consumers accept the miss because a miss is the cheap direction.
+ * - the relation is `\S+` — quoted or bare, unparsed. This function answers
+ *   "which COLUMN", never "which relation".
+ *
+ * The read-path phrasing `column "bogus" does not exist` is a different
+ * sentence with no relation in it, so it does not match — and it does not need
+ * to: it carries no missing-table substring, which is the whole hole this
+ * module exists for.
+ */
+declare function matchMissingColumnOfRelation(message: string): string | undefined;
+/**
+ * The same quirk, **wider**: does this message talk about any sub-object of a
+ * relation, in any verdict?
+ *
+ * Drops all three of {@link matchMissingColumnOfRelation}'s anchors — the
+ * literal `column`, the `[a-z0-9_]+` identifier shape, and the trailing
+ * `does not exist` — so it also recognises `constraint "uq_x" of relation "y"
+ * does not exist` (42704), `column "x" of relation "y" already exists` (42701),
+ * and every other sub-object Postgres phrases this way.
+ *
+ * For **exclusion** callers only. A `true` here means "the relation is present,
+ * so whatever else this error is, it is not a missing table"; it does not mean
+ * the error is benign and it names nothing. Using it to extract would be a
+ * category error — there is no capture group precisely so that it cannot be.
+ */
+declare function isRelationSubObjectPhrase(message: string): boolean;
+
+/**
+ * Whether a thrown driver error is a unique/primary-key constraint violation.
+ *
+ * Reads all three channels in turn — `code`, `errno`, `message` — then one step
+ * down the `cause` chain, because pool and query-builder layers re-throw with
+ * the original attached. A plain string is judged on the message channel, so a
+ * caller that has already unwrapped `err.message` can pass it straight in.
+ *
+ * **Unrecognised is always `false`.** The default has to be "not a conflict":
+ * a false positive relabels an unrelated failure as the client's fault (a 409
+ * an SDK will not retry, pointing at a value that is fine), while a false
+ * negative costs only the generic envelope that was the status quo.
+ *
+ * @param error - the thrown value, of any shape.
+ *
+ * @example
+ * ```ts
+ * catch (error) {
+ *   if (isUniqueViolationError(error)) return conflict();  // 409 UNIQUE_VIOLATION
+ *   throw error;
+ * }
+ * ```
+ */
+declare function isUniqueViolationError(error: unknown): boolean;
+/**
+ * Which column a unique-constraint violation was raised on — or `undefined`
+ * when the dialect did not determinably name one (#6544).
+ *
+ * ## The contract, and why it is this narrow
+ *
+ * **A value comes back only when the identifier the driver printed is
+ * determinably a COLUMN.** When a dialect names an *index* instead — MySQL's
+ * `Duplicate entry 'a@b.com' for key 'idx_email_unique'`, Postgres'
+ * `violates unique constraint "sys_user_email_key"`, SQLite's
+ * `UNIQUE constraint failed: index 'idx_lower_email'` — the answer is
+ * `undefined`, never the index name.
+ *
+ * That is the maintainer's 2026-08-08 ruling on #6544, and the reasoning is the
+ * caller's, not this module's: **an index name mistaken for a column is worse
+ * than no answer at all.**
+ *
+ *  - `@objectstack/rest`'s import runner renders this into a form field —
+ *    "A record with this `email` already exists." An index name there points
+ *    the user at a field that does not exist on the object, so they cannot act
+ *    on it; `undefined` degrades to generic copy, which is merely less helpful.
+ *  - #5495's autonumber-retry branch asks a yes/no question of the answer —
+ *    "is the conflicting column the autonumber field?" — and an index name
+ *    produces a *wrong retry decision*, not a vaguer one.
+ *
+ * ⛔ **The accepted cost: MySQL deployments usually get no column.** MySQL's
+ * duplicate-entry message names the index and never the column, so there is
+ * nothing here to read. That is deliberate. Do not "improve" this by deriving a
+ * column from an index name (`idx_email_unique` → `email`, or MySQL 8's
+ * `for key 'sys_user.email'` → `email`): index names are free-form, a
+ * deployment's may match no column at all, and a plausible-looking wrong field
+ * is exactly the failure this export exists to avoid. If MySQL must name
+ * columns, the answer is a schema lookup of the index — a different, wider
+ * contract — not a guess in this function.
+ *
+ * A **composite** key is `undefined` for the same reason: `Key (tenant_id,
+ * email)=(…)` has no single offending column, and naming the first is the same
+ * class of wrong answer.
+ *
+ * ## What it reads
+ *
+ * Gated on {@link isUniqueViolationError}, so a NOT NULL or FOREIGN KEY failure
+ * can never reach the extraction — SQLite's `NOT NULL constraint failed: t.c`
+ * shares its shape with the positive and is refused at the gate, not by the
+ * patterns. Then `message`, then `detail` (node-postgres keeps its `DETAIL:`
+ * line there), then one step down the `cause` chain, bounded exactly as the
+ * predicate's walk is. A bare string is read as a message, so a caller holding
+ * only `err.message` can pass it straight in.
+ *
+ * @param error - the thrown value, of any shape.
+ * @returns the conflicting column, or `undefined` when none is determinable.
+ *
+ * @example
+ * ```ts
+ * const column = uniqueViolationColumn(error);
+ * return column
+ *   ? `A record with this ${column} already exists.`
+ *   : 'A record with this value already exists.';
+ * ```
+ */
+declare function uniqueViolationColumn(error: unknown): string | undefined;
+
 /**
  * [ADR-0120 D5e] The `isolated`-posture install gate for `'global'` uniqueness.
  *
@@ -904,4 +1095,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type EnvelopeResponse, GLOBAL_UNIQUE_CONFIRMATION_REQUIRED, GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION, type GlobalUniqueAttestation, type GlobalUniqueFinding, type IKernel, INTERNAL_ERROR_MESSAGE, type KeysetPageQuery, type KeysetWalk, type KeysetWalkOptions, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declaredIndexUniqueIsGlobal, declaresServerFault, describeGlobalUniqueFinding, emitDegradedBootBanner, fieldUniqueIsGlobal, globalUniqueFindingId, isMcpServerEnabled, isModuleNotFoundError, isPlatformOwnedObject, keysetWalk, looksLikeInternalErrorLeak, postureGatesGlobalUniques, readEnvWithDeprecation, recordGlobalUniqueAttestation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, sendError, sendOk, stampSearchPinyinEnabled, unconfirmedGlobalUniques };
+export { type EnvelopeResponse, GLOBAL_UNIQUE_CONFIRMATION_REQUIRED, GLOBAL_UNIQUE_ISOLATED_PRESCRIPTION, type GlobalUniqueAttestation, type GlobalUniqueFinding, type IKernel, INTERNAL_ERROR_MESSAGE, type KeysetPageQuery, type KeysetWalk, type KeysetWalkOptions, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, buildGlobalUniqueStopMessage, collectConfiguredLocales, collectGlobalUniques, declaredIndexUniqueIsGlobal, declaresServerFault, describeGlobalUniqueFinding, emitDegradedBootBanner, fieldUniqueIsGlobal, globalUniqueFindingId, isMcpServerEnabled, isModuleNotFoundError, isPlatformOwnedObject, isRelationSubObjectPhrase, isUniqueViolationError, keysetWalk, looksLikeInternalErrorLeak, matchMissingColumnOfRelation, postureGatesGlobalUniques, readEnvWithDeprecation, recordGlobalUniqueAttestation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, sendError, sendOk, stampSearchPinyinEnabled, unconfirmedGlobalUniques, uniqueViolationColumn };

package/dist/index.js

@@ -36,8 +36,11 @@ __export(index_exports, {
   isMcpServerEnabled: () => isMcpServerEnabled,
   isModuleNotFoundError: () => isModuleNotFoundError,
   isPlatformOwnedObject: () => isPlatformOwnedObject,
+  isRelationSubObjectPhrase: () => isRelationSubObjectPhrase,
+  isUniqueViolationError: () => isUniqueViolationError,
   keysetWalk: () => keysetWalk,
   looksLikeInternalErrorLeak: () => looksLikeInternalErrorLeak,
+  matchMissingColumnOfRelation: () => matchMissingColumnOfRelation,
   postureGatesGlobalUniques: () => postureGatesGlobalUniques,
   readEnvWithDeprecation: () => readEnvWithDeprecation,
   recordGlobalUniqueAttestation: () => recordGlobalUniqueAttestation,
@@ -53,7 +56,8 @@ __export(index_exports, {
   sendError: () => sendError,
   sendOk: () => sendOk,
   stampSearchPinyinEnabled: () => stampSearchPinyinEnabled,
-  unconfirmedGlobalUniques: () => unconfirmedGlobalUniques
+  unconfirmedGlobalUniques: () => unconfirmedGlobalUniques,
+  uniqueViolationColumn: () => uniqueViolationColumn
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -280,6 +284,82 @@ function sendError(res, status, code, message, extra) {
   res.status(status).json({ success: false, error: { code, message, ...extra } });
 }
 
+// src/relation-sub-object.ts
+function matchMissingColumnOfRelation(message) {
+  return MISSING_COLUMN_OF_RELATION.exec(message)?.[1];
+}
+function isRelationSubObjectPhrase(message) {
+  return RELATION_SUB_OBJECT.test(message);
+}
+var MISSING_COLUMN_OF_RELATION = /column\s+["'`]([a-z0-9_]+)["'`]\s+of relation\s+\S+\s+does not exist/i;
+var RELATION_SUB_OBJECT = /["'`][^"'`]+["'`]\s+of relation\s/i;
+
+// src/unique-violation.ts
+var UNIQUE_VIOLATION = {
+  codes: /* @__PURE__ */ new Set(["23505", "ER_DUP_ENTRY", "SQLITE_CONSTRAINT_UNIQUE"]),
+  errnos: /* @__PURE__ */ new Set([1062]),
+  message: /unique constraint|unique violation|duplicate key|duplicate entry/i
+};
+var MAX_CAUSE_DEPTH = 4;
+function isUniqueViolationError(error) {
+  return matchesUniqueViolation(error, 0);
+}
+function matchesUniqueViolation(error, depth) {
+  if (error === null || error === void 0 || depth > MAX_CAUSE_DEPTH) return false;
+  if (typeof error === "string") return UNIQUE_VIOLATION.message.test(error);
+  if (typeof error !== "object") return false;
+  const err = error;
+  if (typeof err.code === "string" && UNIQUE_VIOLATION.codes.has(err.code)) return true;
+  if (typeof err.code === "number" && UNIQUE_VIOLATION.errnos.has(err.code)) return true;
+  if (typeof err.errno === "number" && UNIQUE_VIOLATION.errnos.has(err.errno)) return true;
+  if (typeof err.message === "string" && UNIQUE_VIOLATION.message.test(err.message)) return true;
+  return matchesUniqueViolation(err.cause, depth + 1);
+}
+var SQLITE_TARGETS = /unique constraint failed:\s*([^\n]*)/i;
+var POSTGRES_DETAIL_TARGETS = /\bkey \(([^)]+)\)=\(/i;
+var SQLITE_INDEX_FORM = /^index\b/i;
+var PLAIN_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+function bareIdentifier(raw) {
+  const stripped = raw.trim().replace(/[`"'[\]]/g, "");
+  const dot = stripped.lastIndexOf(".");
+  return dot >= 0 ? stripped.slice(dot + 1) : stripped;
+}
+function soleColumn(targets) {
+  const names = targets.split(",").map(bareIdentifier);
+  if (names.length !== 1) return void 0;
+  const [name] = names;
+  return PLAIN_IDENTIFIER.test(name) ? name : void 0;
+}
+function columnFromText(text) {
+  const sqlite = SQLITE_TARGETS.exec(text);
+  if (sqlite) {
+    const targets = sqlite[1].trim();
+    return SQLITE_INDEX_FORM.test(targets) ? void 0 : soleColumn(targets);
+  }
+  const postgres = POSTGRES_DETAIL_TARGETS.exec(text);
+  if (postgres) return soleColumn(postgres[1]);
+  return void 0;
+}
+function findUniqueViolationColumn(error, depth) {
+  if (error === null || error === void 0 || depth > MAX_CAUSE_DEPTH) return void 0;
+  if (typeof error === "string") return columnFromText(error);
+  if (typeof error !== "object") return void 0;
+  const err = error;
+  if (typeof err.message === "string") {
+    const fromMessage = columnFromText(err.message);
+    if (fromMessage !== void 0) return fromMessage;
+  }
+  if (typeof err.detail === "string") {
+    const fromDetail = columnFromText(err.detail);
+    if (fromDetail !== void 0) return fromDetail;
+  }
+  return findUniqueViolationColumn(err.cause, depth + 1);
+}
+function uniqueViolationColumn(error) {
+  if (!isUniqueViolationError(error)) return void 0;
+  return findUniqueViolationColumn(error, 0);
+}
+
 // src/unique-scope-install-gate.ts
 var import_security2 = require("@objectstack/spec/security");
 var SYS_OBJECT_PREFIXES = ["sys_", "base_"];
@@ -395,8 +475,11 @@ function postureGatesGlobalUniques(posture) {
   isMcpServerEnabled,
   isModuleNotFoundError,
   isPlatformOwnedObject,
+  isRelationSubObjectPhrase,
+  isUniqueViolationError,
   keysetWalk,
   looksLikeInternalErrorLeak,
+  matchMissingColumnOfRelation,
   postureGatesGlobalUniques,
   readEnvWithDeprecation,
   recordGlobalUniqueAttestation,
@@ -412,6 +495,7 @@ function postureGatesGlobalUniques(posture) {
   sendError,
   sendOk,
   stampSearchPinyinEnabled,
-  unconfirmedGlobalUniques
+  unconfirmedGlobalUniques,
+  uniqueViolationColumn
 });
 //# sourceMappingURL=index.js.map