@kywi-software/core 0.14.0 → 0.15.0

package/dist/schema/components.js

@@ -1,15 +1,26 @@
-import { pgTable, uuid, text, varchar, jsonb, timestamp, index, uniqueIndex } from 'drizzle-orm/pg-core';
-import { kywiSites, kywiContent } from './base.js';
+import { sql } from 'drizzle-orm';
+import { pgTable, uuid, text, varchar, jsonb, timestamp, index, uniqueIndex, check } from 'drizzle-orm/pg-core';
+import { kywiSites, kywiContent, kywiSectionTemplates } from './base.js';
 export const kywiComponents = pgTable('kywi_components', {
     id: uuid('id').primaryKey().defaultRandom(),
     siteId: uuid('site_id').notNull().references(() => kywiSites.id),
     name: text('name').notNull(),
     description: text('description'),
-    // 'module' | 'section' | 'variantContainer'. A `variantContainer` component
-    // stores a whole VariantContainer (its default sections + every variant arm);
-    // audience/experiment resolution still happens at render time, exactly as for
-    // an inline one (kywi-cms#147).
-    type: varchar('type', { length: 20 }).notNull(),
+    // 'module' | 'section' | 'variantContainer' | 'moduleVariantContainer'.
+    // A `variantContainer` component stores a whole section-level VariantContainer
+    // (its default sections + every variant arm) and a `moduleVariantContainer` the
+    // whole column-level one (its default module + every arm); audience/experiment
+    // resolution still happens at render time, exactly as for an inline one
+    // (kywi-cms#147, #170).
+    //
+    // WIDENED FROM 20 TO 40 (kywi-cms#170). `'moduleVariantContainer'` is 22
+    // characters, so every insert of the fourth kind failed with Postgres
+    // `22001 value too long for type character varying(20)` — a 500, not a
+    // validation error, because the string passes every check in the application
+    // and only the column refuses it. Widening a varchar is metadata-only on
+    // Postgres and MySQL alike (no table rewrite, no backfill), and 40 leaves room
+    // for a fifth name without a second migration.
+    type: varchar('type', { length: 40 }).notNull(),
     moduleType: varchar('module_type', { length: 100 }), // for module components: the module name (e.g., 'hero')
     // ModuleNode props+style for modules, full LayoutSection for sections,
     // full VariantContainer for variantContainer components.
@@ -19,43 +30,123 @@ export const kywiComponents = pgTable('kywi_components', {
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
 });
 /**
- * Where every linked component instance is placed (kywi-cms#147).
+ * Where every linked component instance is placed (kywi-cms#147, #156).
  *
  * A `componentId` link lives only inside a layout's JSONB, so answering "how
  * many instances does this component have, on how many pages?" — the blast
  * radius the save-fork dialog must name, and the gate on deleting a component —
  * would otherwise mean scanning and parsing every layout in the site. This is
  * the normalised index of those links, maintained transactionally by
- * `setContentLayout` (the one and only layout write path) and rebuilt from
- * scratch by `reindexComponentInstances`, which `kywi migrate` runs as a
- * post-step so existing installs are backfilled with no operator action.
+ * `setContentLayout` and `setSectionTemplateDefinition` (the only two layout
+ * write paths) and rebuilt from scratch by `reindexComponentInstances`, which
+ * `kywi migrate` runs as a post-step so existing installs are backfilled with no
+ * operator action.
+ *
+ * HOLDER-POLYMORPHIC (kywi-cms#156). A layout document lives in one of two
+ * places: a page (`kywi_content.layout`) or a saved layout / blueprint
+ * (`kywi_section_templates.definition`). Until #156 only the first was
+ * indexable, because `content_id` was NOT NULL — so a component linked from a
+ * blueprint reported "0 instances across 0 pages", the save fork on the
+ * blueprint canvas had to run inert rather than quote a number that was a lie,
+ * and deleting the component left the blueprint holding a dangling link
+ * forever. A row now names exactly ONE holder: `content_id` or `blueprint_id`,
+ * never both and never neither, which the CHECK below enforces at the storage
+ * layer rather than by convention.
+ *
+ * Two nullable FKs rather than an untyped `holder_id`, deliberately: CASCADE is
+ * what guarantees a deleted holder cannot inflate a count, and a polymorphic id
+ * column cannot carry a foreign key at all. That property is the one the whole
+ * index rests on.
+ *
+ * `holder_kind` names the holder in one column, so a reader — a human at a psql
+ * prompt, a report, a future join — can tell what a row is without inferring it
+ * from which of two nullable ids happens to be set. It is redundant BY
+ * CONSTRUCTION and the CHECK below is what keeps it honest: the constraint ties
+ * the label to the columns in both directions, so `holder_kind = 'blueprint'`
+ * with a `content_id` set is not a row this table can hold. Without that tie the
+ * column would be a comment the database does not check, and a drifted label is
+ * worse than no label. It defaults to `'content'`, which is exactly what every
+ * pre-#156 row is.
+ *
+ * The query layer partitions on the ID columns, not on this label — `NULL` is
+ * the thing an index and a `WHERE` can both use, and it is the half the CHECK
+ * would still enforce if the label were ever dropped.
  *
  * The index is a derived cache: it is authoritative for *counts*, never for
  * rewrites. `detachComponentEverywhere` deliberately re-scans layouts instead of
- * trusting it, so a page can never be left holding a dangling link.
+ * trusting it, so neither a page nor a blueprint can be left holding a dangling
+ * link.
  *
  * Rows are scoped by `siteId` (components are per-site in v1) and cascade away
- * with either side of the link, so neither deleting a page nor deleting a
- * component can leave a stale row inflating a count.
+ * with every side of the link, so deleting a page, a blueprint, or a component
+ * can never leave a stale row inflating a count.
+ */
+/** The two things a layout document can live in — see {@link kywiComponentInstances}. */
+export const COMPONENT_HOLDER_KINDS = ['content', 'blueprint'];
+/**
+ * `content_type` for a blueprint row.
+ *
+ * The column is denormalised display data for the usage payload and stays NOT
+ * NULL, but a blueprint has no content type — it is not a document of any type,
+ * it is a stencil. A sentinel rather than an empty string so a reader who meets
+ * one in the raw table knows it is deliberate, and so a UI that groups by
+ * content type cannot silently render it as a real type name.
  */
+export const BLUEPRINT_CONTENT_TYPE = '__blueprint__';
 export const kywiComponentInstances = pgTable('kywi_component_instances', {
     id: uuid('id').primaryKey().defaultRandom(),
     componentId: uuid('component_id').notNull().references(() => kywiComponents.id, { onDelete: 'cascade' }),
     siteId: uuid('site_id').notNull().references(() => kywiSites.id),
-    contentId: uuid('content_id').notNull().references(() => kywiContent.id, { onDelete: 'cascade' }),
-    /** `kywi_content.content_type_name` of the placing document, denormalised for the usage payload. */
+    /**
+     * `'content'` | `'blueprint'` — which column below holds this row's holder,
+     * said once rather than inferred from two nullable ids. Tied to those ids by
+     * the CHECK below, so it cannot drift out of agreement with them. Defaults to
+     * `'content'`, which is what every row written before #156 is.
+     */
+    holderKind: varchar('holder_kind', { length: 20 }).notNull().default('content'),
+    /** Set iff `holder_kind = 'content'`. */
+    contentId: uuid('content_id').references(() => kywiContent.id, { onDelete: 'cascade' }),
+    /** Set iff `holder_kind = 'blueprint'`. */
+    blueprintId: uuid('blueprint_id').references(() => kywiSectionTemplates.id, { onDelete: 'cascade' }),
+    /**
+     * `kywi_content.content_type_name` of the placing document, denormalised for
+     * the usage payload — {@link BLUEPRINT_CONTENT_TYPE} on a blueprint row.
+     */
     contentType: varchar('content_type', { length: 100 }).notNull(),
     /** The layout node id carrying the link (section id, module id, or variantContainer id). */
     nodeId: text('node_id').notNull(),
     updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
 }, (t) => ({
-    // One row per placement. Also the count-by-component index: `component_id` is
-    // the leading column, so `WHERE component_id = $1` (the usage read and the
-    // delete gate) uses this index — a separate single-column index would be
-    // redundant.
+    // One row per placement, per holder kind. PARTIAL rather than one unique over
+    // `coalesce(content_id, blueprint_id)`: a partial index is the honest
+    // statement of the constraint (it says which rows it governs), it is smaller,
+    // and it stays a plain b-tree over real columns, so the planner can use it for
+    // the reads below. `component_id` leads both, so `WHERE component_id = $1`
+    // (the usage read and the delete gate) is indexed by either — a separate
+    // single-column index would be redundant.
     placementUnique: uniqueIndex('kywi_component_instances_placement')
-        .on(t.componentId, t.contentId, t.nodeId),
-    // `setContentLayout` rewrites the rows for one document on every save.
+        .on(t.componentId, t.contentId, t.nodeId)
+        .where(sql `${t.contentId} is not null`),
+    blueprintPlacementUnique: uniqueIndex('kywi_component_instances_blueprint_placement')
+        .on(t.componentId, t.blueprintId, t.nodeId)
+        .where(sql `${t.blueprintId} is not null`),
+    // `setContentLayout` rewrites the rows for one document on every save;
+    // `setSectionTemplateDefinition` does the same for one blueprint.
     byContent: index('kywi_component_instances_by_content').on(t.contentId),
+    byBlueprint: index('kywi_component_instances_by_blueprint').on(t.blueprintId),
+    // Exactly one holder, AND `holder_kind` agrees with which one it is.
+    //
+    // The first half is what the nullability costs: without it, the change that
+    // makes blueprints indexable would also admit a holderless row — one no
+    // cascade can ever clean up, inflating a count and blocking a delete forever.
+    //
+    // The second half is what keeps `holder_kind` a fact rather than a comment.
+    // Naming the two legal shapes in full, instead of `<>` plus a separate
+    // enum-style check, is what makes the constraint total: it pins the label to
+    // the columns in BOTH directions, so `holder_kind = 'blueprint'` with a
+    // `content_id` set, or a value that is neither of the two kinds, are both
+    // shapes this table cannot hold.
+    oneHolder: check('kywi_component_instances_one_holder', sql `(${t.holderKind} = 'content' and ${t.contentId} is not null and ${t.blueprintId} is null)
+      or (${t.holderKind} = 'blueprint' and ${t.blueprintId} is not null and ${t.contentId} is null)`),
 }));
 //# sourceMappingURL=components.js.map

package/dist/schema/components.js.map

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