rimecms 0.31.5 → 0.32.0

package/dist/adapter-sqlite/where.server.js

@@ -1,20 +1,23 @@
 import { RimeError } from '../core/errors/index.js';
 import { getFieldAtPath } from '../core/fields/util.js';
-import { logger } from '../core/logger/index.server.js';
-import { hasVersionsSuffix, withLocalesSuffix } from '../core/naming.js';
+import { logger } from '../core/logger.server.js';
 import { RelationFieldBuilder } from '../fields/relation/index.js';
 import {} from '../index.js';
 import * as drizzleORM from 'drizzle-orm';
 import { and, eq, getTableColumns, inArray, or } from 'drizzle-orm';
-export const buildWhereParam = ({ query, slug, db, locale, tables, configCtx }) => {
+import { localeOrder } from './locales.server.js';
+import { baseTableName, tableName } from './naming.server.js';
+export const buildWhereParam = ({ query, slug, db, locale, tables, configCtx, base, rootTable }) => {
+    /** `slug` names a content table standing in for `base`, not a prototype's own rows. */
+    const isShadow = !!base;
     // Helper to get table by key with correct typing
     function getTable(key) {
         return tables[key];
     }
     function getTablesAndColumns(slug) {
         // Get main table and localized table if applicable
-        const table = getTable(slug);
-        const tableNameLocales = withLocalesSuffix(slug);
+        const table = getTable(baseTableName(slug));
+        const tableNameLocales = tableName({ owner: baseTableName(slug), branch: 'locales' });
         const tableLocales = getTable(tableNameLocales);
         // Get localized and unlocalized columns
         const localizedColumns = locale && tableNameLocales in tables ? Object.keys(getTableColumns(tableLocales)) : [];
@@ -23,7 +26,13 @@ export const buildWhereParam = ({ query, slug, db, locale, tables, configCtx })
     }
     const { 
     // Get main table and localized table if applicable
-    table, tableLocales, localizedColumns, unlocalizedColumns } = getTablesAndColumns(slug);
+    table: ownTable, tableLocales, localizedColumns, unlocalizedColumns } = getTablesAndColumns(slug);
+    /** What the outer condition names — the caller's alias where there is one. */
+    const table = rootTable ?? ownTable;
+    // The base row a versions table hangs off, and its columns. `baseTableName`, not the bare
+    // slug: a camelCase slug is not a table name.
+    const baseTable = isShadow ? getTable(baseTableName(base)) : undefined;
+    const baseColumns = baseTable ? Object.keys(getTableColumns(baseTable)) : [];
     const buildCondition = (conditionObject) => {
         // Handle nested AND conditions
         if ('and' in conditionObject && Array.isArray(conditionObject.and)) {
@@ -39,28 +48,30 @@ export const buildWhereParam = ({ query, slug, db, locale, tables, configCtx })
                 .filter(Boolean);
             return subConditions.length ? or(...subConditions) : false;
         }
-        conditionObject = normalizedForVersion(conditionObject, slug);
+        conditionObject = normalizedForShadow(conditionObject, isShadow);
         const { 
         // Get condition members
         column, sqlColumn, fn, operator, rawValue, value } = getConditionMembers(conditionObject);
-        // Handle hierarchy fields (_parent, _position) in versioned collections
-        if (shouldHandleVersionedHierarchyFields(slug, sqlColumn)) {
-            // Get the root table name by removing the '_versions' suffix
-            const rootSlug = slug.replace('_versions', '');
-            const rootTable = getTable(rootSlug);
-            // Query the root table for the hierarchy field
-            return inArray(table.ownerId, db.select({ ownerId: rootTable.id }).from(rootTable).where(fn(rootTable[sqlColumn], value)));
-        }
         // Handle regular fields
         if (unlocalizedColumns.includes(sqlColumn)) {
             return fn(table[sqlColumn], value);
         }
-        // Handle localized fields
+        // A localized column is compared as a read would show it: the first locale in the fallback
+        // order that holds a value, `''` counting as none — so a page found by its slug in one locale
+        // is found by the same slug in a locale it was not translated to yet.
         if (locale && localizedColumns.includes(sqlColumn)) {
-            return inArray(table.id, db
-                .select({ id: tableLocales.ownerId })
-                .from(tableLocales)
-                .where(and(fn(tableLocales[sqlColumn], value), eq(tableLocales.locale, locale))));
+            const { sql } = drizzleORM;
+            const order = localeOrder(configCtx, locale) ?? [locale];
+            const valueIn = (code) => sql `NULLIF((SELECT ${tableLocales[sqlColumn]} FROM ${tableLocales} WHERE ${tableLocales.ownerId} = ${table.id} AND ${tableLocales.locale} = ${code}), '')`;
+            const resolved = order.length > 1
+                ? sql `COALESCE(${sql.join(order.map(valueIn), sql `, `)})`
+                : valueIn(order[0]);
+            return fn(resolved, value);
+        }
+        // A column the base row keeps — the hierarchy columns, and any `$root()` field — reached
+        // through `ownerId` when the table queried is the versions table.
+        if (baseTable && baseColumns.includes(sqlColumn)) {
+            return inArray(table.ownerId, db.select({ ownerId: baseTable.id }).from(baseTable).where(fn(baseTable[sqlColumn], value)));
         }
         // Look for a relation field
         // Get document config
@@ -136,7 +147,7 @@ export const buildWhereParam = ({ query, slug, db, locale, tables, configCtx })
                 .select({ id: relatedTable.id })
                 .from(relatedTable)
                 .where(relatedCondition);
-            const relsTable = getTable(`${slug}Rels`);
+            const relsTable = getTable(tableName({ owner: baseTableName(slug), child: { kind: 'rels' } }));
             // Join relation rows to documents by matching the related id and the relation path
             const ownersWithMatching = db
                 .select({ id: relsTable.ownerId })
@@ -166,7 +177,7 @@ export const buildWhereParam = ({ query, slug, db, locale, tables, configCtx })
             fieldConfig.get.localized,
             fieldConfig.get.many
         ];
-        const relsTableName = `${slug}Rels`;
+        const relsTableName = tableName({ owner: baseTableName(slug), child: { kind: 'rels' } });
         const relsTable = getTable(relsTableName);
         // Helpers for building common relation-owner subqueries (operate on the relations table)
         const buildOwnersWithTotalCount = (count) => db
@@ -307,25 +318,24 @@ function getConditionMembers(obj) {
     const value = formatValue({ operator, value: rawValue });
     return { column, sqlColumn, fn, operator, rawValue, value };
 }
-// Determine if we should handle versioned hierarchy fields
-function shouldHandleVersionedHierarchyFields(slug, sqlColumn) {
-    return (hasVersionsSuffix(slug) &&
-        (sqlColumn === '_parent' || sqlColumn === '_position' || sqlColumn === '_path'));
-}
 // Normalize condition object for versioned collections
-function normalizedForVersion(conditionObject, slug) {
-    // Handle id field for versioned collections
-    // if "id" inside the query it should refer to the root table
-    if (hasVersionsSuffix(slug) && 'id' in conditionObject) {
-        // Replace id with ownerId and keep the same operator and value
+/**
+ * Retargets the two id conditions when the table being queried is a versions table.
+ *
+ * A caller filtering by `id` means the document, which is the base row — on a versions table that is
+ * `ownerId`. `versionId` means the content row itself, which is the versions table's own `id`.
+ */
+function normalizedForShadow(conditionObject, isShadow) {
+    if (!isShadow)
+        return conditionObject;
+    // "id" refers to the document, so it resolves against the base row this versions hangs off.
+    if ('id' in conditionObject) {
         const idOperator = conditionObject.id;
         delete conditionObject.id;
         conditionObject.ownerId = idOperator;
     }
-    // Handle versionId field for versioned collections
-    // if "versionId" inside the query it should refer to the id of the version table (current)
-    if (hasVersionsSuffix(slug) && 'versionId' in conditionObject) {
-        // Replace id with ownerId and keep the same operator and value
+    // "versionId" refers to the content row, which is this table's own id.
+    if ('versionId' in conditionObject) {
         const idOperator = conditionObject.versionId;
         delete conditionObject.versionId;
         conditionObject.id = idOperator;

package/dist/adapter-sqlite/write.server.d.ts

@@ -0,0 +1,166 @@
+import type { VersionsTable } from '../core/adapter.js';
+import type { OperationQuery } from '../core/pipeline/types.js';
+import type { PrototypeSlug } from '../core/prototype/types.js';
+import type { ConfigContext } from '../core/rime.server.js';
+import type { Dic } from '../util/types.js';
+import { type TableName } from './naming.server.js';
+/**
+ * Writing a prototype's rows — insert, update, delete, and the bootstrap a singleton needs.
+ *
+ * The other half of `read.server.ts`; the vocabulary is written down there. `singleton` decides
+ * what `insert` and `delete` refuse outright, and which row an update resolves when it was handed
+ * no id.
+ *
+ * Two apparent differences between the collection and area facades this replaces turned out to be
+ * nothing: an area's update reset every content row's status with no `where` while a collection
+ * scoped it to `ownerId = id` — the same set for a single row; and a collection split off its
+ * `$root()` fields before writing while an area did not — `splitRootData` returns an empty half
+ * when a config marks none. Both are core's now, and this is handed both halves.
+ */
+/**
+ * Writes a row and, when it has localized columns, its `__$$locales` half.
+ *
+ * Every insert goes through here, a document's and a singleton's bootstrap alike.
+ *
+ * Returns the id actually written, which insertTableRecord derives from `row.id` or generates.
+ */
+export declare const insertRowWithLocales: ({ db, tables }: Deps, args: {
+    table: TableName;
+    row: Dic;
+    now: Date;
+    localized: {
+        data: Dic;
+        isLocalized: boolean;
+        locale?: string;
+    };
+}) => Promise<string>;
+type UpdateArgs = {
+    slug: string;
+    versions?: VersionsTable;
+    /** The base row to write. An area resolves its singleton's id before calling. */
+    id: string;
+    /** What goes on it. */
+    data: Dic;
+    /** And the content row this write also touches, when the caller named one. */
+    content?: {
+        id: string;
+        data: Dic;
+    };
+    locale?: string;
+};
+type Deps = {
+    db: any;
+    tables: Dic;
+};
+/**
+ * Writes the rows the caller's plan names.
+ *
+ * Three branches until 1ec2dfca's successor, decoded here from an enum the caller passed down.
+ * They differed in exactly two facts — is there a second row, and has somebody already written it
+ * — and both are settled before the call now (`core/pipeline/run.server.ts` builds the plan,
+ * `FeatureDefinition.writePlan` refines it). What was left is the same two writes in every case,
+ * so there is one path.
+ *
+ * The content row's *table* is still the adapter's to know: registration carries the versions table, and
+ * where rows live is storage. Which row, and whether to touch it, is the caller's.
+ *
+ * Returns `{ id: data.id || id }`. For an area the two always agree — it is a single row, so any
+ * `id` in its data is that row's — and preferring `data.id` keeps a disagreement visible instead
+ * of silently picking the id of the row that was written.
+ */
+export declare const updatePrototype: ({ db, tables }: Deps, { slug, id, data, content, locale, versions }: UpdateArgs) => Promise<{
+    id: any;
+}>;
+/**
+ * Sets columns on every row of this prototype's own table that `query` matches.
+ *
+ * A primitive: a table, a filter, a patch. It writes exactly the columns it is given — no
+ * `updatedAt`, no children — because the callers that want a bulk column write want the rows left
+ * otherwise alone. Its one caller flips a status column across a document's other content rows,
+ * and depends on `updatedAt` *not* moving: that caller prunes by `updatedAt`, so touching it here
+ * would silently re-order which rows survive.
+ *
+ * With `locale`, a localized column lands on the `__$$locales` branch instead — resolved by
+ * `prepareSchemaData`, the same split every other write goes through, so a caller says "set this
+ * field" without knowing which of the two tables it is in.
+ *
+ * It goes through `buildWhereParam`, so the filter is the same REST-shaped query every other
+ * operation takes rather than a second dialect.
+ */
+export declare const updateWherePrototype: ({ db, tables, configCtx }: DepsWithConfig, { slug, query, data, locale }: {
+    slug: PrototypeSlug;
+    query: OperationQuery;
+    data: Dic;
+    locale?: string;
+}) => Promise<void>;
+/**
+ * Writes a new document: the rows the plan names.
+ *
+ * The insert half of `updatePrototype`, and it reads the same way: the caller says which rows this
+ * write touches, and this executes. Where a versioned config's `$root()` fields go is
+ * `versionsWritePlan`'s statement, made before the call.
+ *
+ * `contentId` names the row the content landed on — the versions row when there is one, the base row
+ * otherwise — which is what the caller hangs blocks, tree nodes and relations off.
+ */
+export declare const insertPrototype: ({ db, tables }: Deps, { slug, data, content, locale, versions }: InsertArgs) => Promise<{
+    id: string;
+    contentId: string;
+}>;
+/**
+ * Reads many documents, merged with the content row each should show.
+ *
+ * The versioned branch queries the base table and pulls one content row per document, because
+ * pagination and ordering are properties of the document rather than of one of its rows.
+ */
+export declare const deletePrototype: ({ db, tables }: Deps, { slug, id }: {
+    slug: string;
+    id: string;
+}) => Promise<string | undefined>;
+/**
+ * The ids of the documents whose `_parent` is `parentId`, in `_position` order.
+ *
+ * Cannot go through `findMany`: hierarchy lives on the base table while a versioned prototype's
+ * `where` resolves against the content table. `_parent` and `_position` are columns the adapter
+ * writes itself, so answering this is its job.
+ */
+/**
+ * Brings a singleton's row into being if it is not already there. Boot only.
+ *
+ * Deliberately not an `insert`: it takes no data beyond the blank document, hands back no id,
+ * and a second call does nothing. That shape is what lets a singleton have no create at all
+ * while its one row still comes from somewhere.
+ */
+export declare const ensurePrototypeExists: ({ db, tables }: Deps, { slug, blank, locale, versions }: EnsureExistsArgs) => Promise<void>;
+type InsertArgs = {
+    versions?: VersionsTable;
+    slug: string;
+    data: Dic;
+    /** No `id`: the row does not exist yet. See `Adapter.insert`. */
+    content?: {
+        data: Dic;
+    };
+    locale?: string;
+};
+type EnsureExistsArgs = {
+    versions?: VersionsTable;
+    slug: string;
+    /**
+     * The document to write. Already shaped by whatever the prototype's features say a bootstrapped
+     * first document carries — see `FeatureDefinition.blank` with intent `'seed'`. This module
+     * writes it and asks nothing about what is in it.
+     */
+    blank: Dic;
+    locale?: string;
+};
+/**
+ * `updateWhere` alone reaches `buildWhereParam`, which is typed against the generated schema
+ * rather than against `Dic`. Confining the looseness to the one operation that needs it beats
+ * widening `Deps` for everything.
+ */
+type DepsWithConfig = {
+    db: any;
+    tables: any;
+    configCtx: ConfigContext;
+};
+export {};

package/dist/adapter-sqlite/write.server.js

@@ -0,0 +1,272 @@
+import { normalizeQuery } from '../core/pipeline/query.js';
+import { and, eq, inArray } from 'drizzle-orm';
+import { RimeError } from '../core/errors/index.js';
+import { baseTableName, tableName } from './naming.server.js';
+import * as adapterUtil from './columns.server.js';
+import { buildWhereParam } from './where.server.js';
+/**
+ * Writing a prototype's rows — insert, update, delete, and the bootstrap a singleton needs.
+ *
+ * The other half of `read.server.ts`; the vocabulary is written down there. `singleton` decides
+ * what `insert` and `delete` refuse outright, and which row an update resolves when it was handed
+ * no id.
+ *
+ * Two apparent differences between the collection and area facades this replaces turned out to be
+ * nothing: an area's update reset every content row's status with no `where` while a collection
+ * scoped it to `ownerId = id` — the same set for a single row; and a collection split off its
+ * `$root()` fields before writing while an area did not — `splitRootData` returns an empty half
+ * when a config marks none. Both are core's now, and this is handed both halves.
+ */
+/**
+ * Writes a row and, when it has localized columns, its `__$$locales` half.
+ *
+ * Every insert goes through here, a document's and a singleton's bootstrap alike.
+ *
+ * Returns the id actually written, which insertTableRecord derives from `row.id` or generates.
+ */
+export const insertRowWithLocales = async ({ db, tables }, args) => {
+    const id = await adapterUtil.insertTableRecord(db, tables, args.table, {
+        ...args.row,
+        createdAt: args.now,
+        updatedAt: args.now
+    });
+    // A locales row says the locale was written. With nothing to say there is no row, and the
+    // first write in that locale makes one — the same for a document and for a singleton's
+    // bootstrap, whose seeded `id` is not a value.
+    const { data, isLocalized, locale } = args.localized;
+    const written = Object.entries(data).some(([key, value]) => key !== 'id' && value !== null && value !== undefined);
+    if (isLocalized && written) {
+        await adapterUtil.insertTableRecord(db, tables, tableName({ owner: args.table, branch: 'locales' }), {
+            ...data,
+            ownerId: id,
+            locale: locale
+        });
+    }
+    return id;
+};
+/**
+ * Writes the rows the caller's plan names.
+ *
+ * Three branches until 1ec2dfca's successor, decoded here from an enum the caller passed down.
+ * They differed in exactly two facts — is there a second row, and has somebody already written it
+ * — and both are settled before the call now (`core/pipeline/run.server.ts` builds the plan,
+ * `FeatureDefinition.writePlan` refines it). What was left is the same two writes in every case,
+ * so there is one path.
+ *
+ * The content row's *table* is still the adapter's to know: registration carries the versions table, and
+ * where rows live is storage. Which row, and whether to touch it, is the caller's.
+ *
+ * Returns `{ id: data.id || id }`. For an area the two always agree — it is a single row, so any
+ * `id` in its data is that row's — and preferring `data.id` keeps a disagreement visible instead
+ * of silently picking the id of the row that was written.
+ */
+export const updatePrototype = async ({ db, tables }, { slug, id, data, content, locale, versions }) => {
+    const now = new Date();
+    await writeRow({ db, tables }, { table: baseTableName(slug), recordId: id, data, locale, now });
+    if (content) {
+        // `versions!` — a plan names a content row only for a prototype that has one, and registration
+        // answered with the versions table for exactly those.
+        await writeRow({ db, tables }, {
+            table: baseTableName(versions.slug),
+            recordId: content.id,
+            data: content.data,
+            locale,
+            now
+        });
+    }
+    return { id: data.id || id };
+};
+/** One row and its locales, which is what both halves of an update come down to. */
+const writeRow = async ({ db, tables }, args) => {
+    const { table, recordId, data, locale, now } = args;
+    const localesTable = tableName({ owner: table, branch: 'locales' });
+    const { mainData, localizedData, isLocalized } = adapterUtil.prepareSchemaData(data, {
+        tables,
+        mainTableName: table,
+        localesTableName: localesTable,
+        locale
+    });
+    await adapterUtil.updateTableRecord(db, tables, table, {
+        recordId,
+        data: { ...mainData, updatedAt: now }
+    });
+    if (isLocalized) {
+        await adapterUtil.upsertLocalizedData(db, tables, localesTable, {
+            ownerId: recordId,
+            data: localizedData,
+            locale: locale
+        });
+    }
+};
+/**
+ * Sets columns on every row of this prototype's own table that `query` matches.
+ *
+ * A primitive: a table, a filter, a patch. It writes exactly the columns it is given — no
+ * `updatedAt`, no children — because the callers that want a bulk column write want the rows left
+ * otherwise alone. Its one caller flips a status column across a document's other content rows,
+ * and depends on `updatedAt` *not* moving: that caller prunes by `updatedAt`, so touching it here
+ * would silently re-order which rows survive.
+ *
+ * With `locale`, a localized column lands on the `__$$locales` branch instead — resolved by
+ * `prepareSchemaData`, the same split every other write goes through, so a caller says "set this
+ * field" without knowing which of the two tables it is in.
+ *
+ * It goes through `buildWhereParam`, so the filter is the same REST-shaped query every other
+ * operation takes rather than a second dialect.
+ */
+export const updateWherePrototype = async ({ db, tables, configCtx }, { slug, query, data, locale }) => {
+    const table = baseTableName(slug);
+    const localesTable = tableName({ owner: table, branch: 'locales' });
+    const where = buildWhereParam({ query: normalizeQuery(query), slug, db, tables, configCtx });
+    const { mainData, localizedData, isLocalized } = adapterUtil.prepareSchemaData(data, {
+        tables,
+        mainTableName: table,
+        localesTableName: localesTable,
+        locale
+    });
+    if (Object.keys(mainData).length) {
+        await db.update(tables[table]).set(mainData).where(where);
+    }
+    if (isLocalized && Object.keys(localizedData).length) {
+        // The branch is keyed by its owner, so the rows to touch are the ones this filter matched.
+        //
+        // An update, never an upsert — `upsertLocalizedData` would *insert* a locales row for a
+        // document that has none yet, and its caller runs during reads. A half-populated
+        // locales row written ahead of the real one is how the multilingual duplicate tests started
+        // failing when this was first written as an upsert.
+        const owners = await db.select({ id: tables[table].id }).from(tables[table]).where(where);
+        const ownerIds = owners.map((owner) => owner.id);
+        if (ownerIds.length) {
+            const branch = tables[localesTable];
+            await db
+                .update(branch)
+                .set(localizedData)
+                .where(and(inArray(branch.ownerId, ownerIds), eq(branch.locale, locale)));
+        }
+    }
+};
+/**
+ * Writes a new document: the rows the plan names.
+ *
+ * The insert half of `updatePrototype`, and it reads the same way: the caller says which rows this
+ * write touches, and this executes. Where a versioned config's `$root()` fields go is
+ * `versionsWritePlan`'s statement, made before the call.
+ *
+ * `contentId` names the row the content landed on — the versions row when there is one, the base row
+ * otherwise — which is what the caller hangs blocks, tree nodes and relations off.
+ */
+export const insertPrototype = async ({ db, tables }, { slug, data, content, locale, versions }) => {
+    const now = new Date();
+    if (versions) {
+        // The base row has no columns for the content, so a plan naming no content half would write
+        // half a document and hang its children off the base row. Loud, rather than silently wrong.
+        if (!content) {
+            throw new RimeError(RimeError.OPERATION_ERROR, `insert on "${slug}" names no content row, and its content lives on "${versions.slug}"`);
+        }
+        const docId = await adapterUtil.insertTableRecord(db, tables, baseTableName(slug), {
+            createdAt: now,
+            updatedAt: now,
+            ...data
+        });
+        const contentTable = baseTableName(versions.slug);
+        const { mainData, localizedData, isLocalized } = adapterUtil.prepareSchemaData(content.data, {
+            tables,
+            mainTableName: contentTable,
+            localesTableName: tableName({ owner: contentTable, branch: 'locales' }),
+            locale
+        });
+        const contentId = await insertRowWithLocales({ db, tables }, {
+            table: contentTable,
+            row: { id: adapterUtil.generatePK(), ownerId: docId, ...mainData },
+            now,
+            localized: { data: localizedData, isLocalized, locale }
+        });
+        return { id: docId, contentId };
+    }
+    const docId = data.id || adapterUtil.generatePK();
+    const table = baseTableName(slug);
+    const { mainData, localizedData, isLocalized } = adapterUtil.prepareSchemaData(data, {
+        tables,
+        mainTableName: table,
+        localesTableName: tableName({ owner: table, branch: 'locales' }),
+        locale
+    });
+    await insertRowWithLocales({ db, tables }, {
+        table,
+        row: { id: docId, ...mainData },
+        now,
+        localized: { data: localizedData, isLocalized, locale }
+    });
+    // No second row exists, so the two ids are the same thing.
+    // No versions: the content is on the base row, so that is the row children hang off.
+    return { id: docId, contentId: docId };
+};
+/**
+ * Reads many documents, merged with the content row each should show.
+ *
+ * The versioned branch queries the base table and pulls one content row per document, because
+ * pagination and ordering are properties of the document rather than of one of its rows.
+ */
+export const deletePrototype = async ({ db, tables }, { slug, id }) => {
+    const table = tables[baseTableName(slug)];
+    const docs = await db.delete(table).where(eq(table.id, id)).returning();
+    if (!docs || !Array.isArray(docs) || !docs.length)
+        throw new RimeError(RimeError.NOT_FOUND);
+    return docs[0].id;
+};
+/**
+ * The ids of the documents whose `_parent` is `parentId`, in `_position` order.
+ *
+ * Cannot go through `findMany`: hierarchy lives on the base table while a versioned prototype's
+ * `where` resolves against the content table. `_parent` and `_position` are columns the adapter
+ * writes itself, so answering this is its job.
+ */
+/**
+ * Brings a singleton's row into being if it is not already there. Boot only.
+ *
+ * Deliberately not an `insert`: it takes no data beyond the blank document, hands back no id,
+ * and a second call does nothing. That shape is what lets a singleton have no create at all
+ * while its one row still comes from somewhere.
+ */
+export const ensurePrototypeExists = async ({ db, tables }, { slug, blank, locale, versions }) => {
+    const table = baseTableName(slug);
+    const [existing] = await db.select({ id: tables[table].id }).from(tables[table]);
+    if (existing)
+        return;
+    const now = new Date();
+    if (versions) {
+        const docId = await adapterUtil.insertTableRecord(db, tables, table, {
+            createdAt: now,
+            updatedAt: now
+        });
+        const contentTable = baseTableName(versions.slug);
+        const { mainData, localizedData, isLocalized } = adapterUtil.prepareSchemaData(blank, {
+            tables,
+            mainTableName: contentTable,
+            localesTableName: tableName({ owner: contentTable, branch: 'locales' }),
+            locale,
+            fillNotNull: true
+        });
+        await insertRowWithLocales({ db, tables }, {
+            table: contentTable,
+            row: { ownerId: docId, ...mainData },
+            now,
+            localized: { data: localizedData, isLocalized, locale }
+        });
+        return;
+    }
+    const localesTable = tableName({ owner: table, branch: 'locales' });
+    const { mainData, localizedData, isLocalized } = adapterUtil.prepareSchemaData(blank, {
+        tables,
+        mainTableName: table,
+        localesTableName: localesTable,
+        locale,
+        fillNotNull: true
+    });
+    await insertRowWithLocales({ db, tables }, {
+        table,
+        row: mainData,
+        now,
+        localized: { data: localizedData, isLocalized, locale }
+    });
+};