@undefineds.co/drizzle-solid 0.2.13 → 0.3.1

package/dist/core/pod-database.d.ts

@@ -1,10 +1,12 @@
 import { entityKind } from 'drizzle-orm';
 import { PodDialect } from './pod-dialect';
 import { PodAsyncSession, type SelectFieldMap, SelectQueryBuilder, InsertQueryBuilder, UpdateQueryBuilder, DeleteQueryBuilder } from './pod-session';
-import { PodTable, SolidSchema, type InferTableData, PodColumnBase, type InstantiateTableOptions } from './schema';
+import { PodTable, SolidSchema, type InferTableData, type ColumnBuilderDataType, PodColumnBase, type InstantiateTableOptions } from './schema';
+import { type PublicQueryCondition, type PublicWhereObject } from './query-conditions';
 import { type TableSubscribeOptions, type EntitySubscribeOptions, type Subscription } from './notifications';
 import { type FederatedError } from './federated';
 import type { DataDiscovery } from './discovery';
+import type { OrderByExpression } from './order-by';
 /**
  * 初始化表选项
  */
@@ -16,6 +18,41 @@ export interface InitOptions {
     /** Shape 保存位置（容器路径或完整 URL），默认为 Pod 根目录下的 /shapes/ */
     shapeLocation?: string;
 }
+type GenericPodTable = PodTable;
+type QueryOrderBy = {
+    column: PodColumnBase | string | OrderByExpression;
+    direction?: 'asc' | 'desc';
+};
+type QueryExactOptions = {
+    columns?: SelectFieldMap;
+    with?: Record<string, boolean | {
+        table?: GenericPodTable;
+    }>;
+};
+type EntityLocator = Record<string, unknown>;
+type QueryFindManyOptions = {
+    where?: PublicWhereObject | PublicQueryCondition;
+    columns?: SelectFieldMap;
+    limit?: number;
+    offset?: number;
+    orderBy?: QueryOrderBy[] | QueryOrderBy;
+    with?: Record<string, boolean | {
+        table?: GenericPodTable;
+    }>;
+};
+type QueryTableHelper<TTable extends GenericPodTable = GenericPodTable> = {
+    findMany<T = InferTableData<TTable>>(options?: QueryFindManyOptions): Promise<T[]>;
+    findFirst<T = InferTableData<TTable>>(options?: QueryFindManyOptions): Promise<T | null>;
+    findByLocator<T = InferTableData<TTable>>(locator: EntityLocator, options?: QueryExactOptions): Promise<T | null>;
+    findByIri<T = InferTableData<TTable>>(iri: string, options?: QueryExactOptions): Promise<T | null>;
+    count(options?: {
+        where?: PublicWhereObject | PublicQueryCondition;
+    }): Promise<number>;
+};
+type QueryProxy<TSchema extends Record<string, unknown>> = {
+    [K in keyof TSchema as TSchema[K] extends GenericPodTable ? K : never]: TSchema[K] extends GenericPodTable ? QueryTableHelper<TSchema[K]> : never;
+};
+type GenericPodColumn = PodColumnBase<ColumnBuilderDataType, boolean, boolean, ColumnBuilderDataType | null>;
 export declare class PodDatabase<TSchema extends Record<string, unknown> = Record<string, never>> {
     dialect: PodDialect;
     session: PodAsyncSession;
@@ -82,17 +119,21 @@ export declare class PodDatabase<TSchema extends Record<string, unknown> = Recor
      * });
      * ```
      */
-    createTable<TColumns extends Record<string, PodColumnBase<any, any, any, any>>>(schema: SolidSchema<TColumns>, options: InstantiateTableOptions): PodTable<TColumns>;
-    select<TTable extends PodTable<any>>(fields?: SelectFieldMap): SelectQueryBuilder<TTable>;
-    insert<TTable extends PodTable<any>>(table: TTable): InsertQueryBuilder<TTable>;
-    update<TTable extends PodTable<any>>(table: TTable): UpdateQueryBuilder<TTable>;
-    delete<TTable extends PodTable<any>>(table: TTable): DeleteQueryBuilder<TTable>;
+    createTable<TColumns extends Record<string, PodColumnBase>>(schema: SolidSchema<TColumns>, options: InstantiateTableOptions): PodTable<TColumns>;
+    select<TTable extends PodTable>(fields?: SelectFieldMap): SelectQueryBuilder<TTable>;
+    insert<TTable extends PodTable>(table: TTable): InsertQueryBuilder<TTable>;
+    update<TTable extends PodTable>(table: TTable): UpdateQueryBuilder<TTable>;
+    delete<TTable extends PodTable>(table: TTable): DeleteQueryBuilder<TTable>;
     execute(query: string): Promise<unknown[]>;
     executeSPARQL(query: string): Promise<unknown[]>;
     batch<TOperations extends readonly unknown[]>(operations: TOperations): Promise<{
         [K in keyof TOperations]: Awaited<TOperations[K]>;
     }>;
-    findFirst<TTable extends PodTable<any>>(table: TTable, where?: Record<string, unknown>): Promise<InferTableData<TTable> | null>;
+    findFirst<TTable extends PodTable>(table: TTable, where?: PublicWhereObject): Promise<InferTableData<TTable> | null>;
+    private getLocatorTemplate;
+    private getRequiredLocatorKeys;
+    private resolveLocatorSubject;
+    findByLocator<TTable extends PodTable>(table: TTable, locator: EntityLocator): Promise<InferTableData<TTable> | null>;
     /**
      * 通过完整 IRI 查询单个实体
      *
@@ -112,7 +153,7 @@ export declare class PodDatabase<TSchema extends Record<string, unknown> = Recor
      * db.findByIri(agentTable, contact.entityUri)
      * ```
      */
-    findByIri<TTable extends PodTable<any>>(table: TTable, iri: string): Promise<InferTableData<TTable> | null>;
+    findByIri<TTable extends PodTable>(table: TTable, iri: string): Promise<InferTableData<TTable> | null>;
     /**
      * 解析 IRI 为文档 URL 和 fragment
      */
@@ -147,7 +188,7 @@ export declare class PodDatabase<TSchema extends Record<string, unknown> = Recor
      * unsubscribe()
      * ```
      */
-    subscribeByIri<TTable extends PodTable<any>>(table: TTable, iri: string, options: EntitySubscribeOptions<InferTableData<TTable>>): Promise<() => void>;
+    subscribeByIri<TTable extends PodTable>(table: TTable, iri: string, options: EntitySubscribeOptions<InferTableData<TTable>>): Promise<() => void>;
     /**
      * 通过完整 IRI 更新单个实体
      *
@@ -165,7 +206,8 @@ export declare class PodDatabase<TSchema extends Record<string, unknown> = Recor
      * )
      * ```
      */
-    updateByIri<TTable extends PodTable<any>>(table: TTable, iri: string, data: Partial<Omit<InferTableData<TTable>, '@id' | 'id'>>): Promise<InferTableData<TTable> | null>;
+    updateByIri<TTable extends PodTable>(table: TTable, iri: string, data: Partial<Omit<InferTableData<TTable>, '@id' | 'id'>>): Promise<InferTableData<TTable> | null>;
+    updateByLocator<TTable extends PodTable>(table: TTable, locator: EntityLocator, data: Partial<Omit<InferTableData<TTable>, '@id' | 'id'>>): Promise<InferTableData<TTable> | null>;
     /**
      * 通过完整 IRI 删除单个实体
      *
@@ -181,7 +223,8 @@ export declare class PodDatabase<TSchema extends Record<string, unknown> = Recor
      * )
      * ```
      */
-    deleteByIri<TTable extends PodTable<any>>(table: TTable, iri: string): Promise<boolean>;
+    deleteByIri<TTable extends PodTable>(table: TTable, iri: string): Promise<boolean>;
+    deleteByLocator<TTable extends PodTable>(table: TTable, locator: EntityLocator): Promise<boolean>;
     transaction<T>(transaction: (tx: PodDatabase<TSchema>) => Promise<T>): Promise<T>;
     getDialect(): PodDialect;
     getSession(): PodAsyncSession;
@@ -222,7 +265,7 @@ export declare class PodDatabase<TSchema extends Record<string, unknown> = Recor
      * subscription.unsubscribe();
      * ```
      */
-    subscribe<TTable extends PodTable<any>>(table: TTable, options: TableSubscribeOptions): Promise<Subscription>;
+    subscribe<TTable extends PodTable>(table: TTable, options: TableSubscribeOptions): Promise<Subscription>;
     /**
      * 解析表对应的订阅主题 URL
      * @param table 表定义
@@ -365,21 +408,22 @@ export declare class PodDatabase<TSchema extends Record<string, unknown> = Recor
     removeSource(source: string): void;
     getSources(): string[];
     addSourcesFromTypeIndex(): Promise<void>;
-    init<TTable extends PodTable<any>>(tables: TTable | TTable[], options?: InitOptions): Promise<void>;
-    init<TTable extends PodTable<any>>(...tables: Array<TTable | TTable[]>): Promise<void>;
+    init<TColumns extends Record<string, GenericPodColumn>, TTable extends PodTable<TColumns>>(tables: TTable | TTable[], options?: InitOptions): Promise<void>;
+    init<TColumns extends Record<string, GenericPodColumn>, TTable extends PodTable<TColumns>>(...tables: Array<TTable | TTable[]>): Promise<void>;
     private queryProxy?;
-    get query(): Record<string, any>;
+    get query(): QueryProxy<TSchema>;
     private buildQueryProxy;
     private eagerLoadWith;
     private dedupeBySubject;
     private resolveIdFromRow;
     private resolveParentKey;
     private resolveIriFromRow;
-    private collectReferenceLookupKeys;
-    private normalizeReferenceValue;
+    private collectLinkLookupKeys;
+    private normalizeLinkValue;
     private normalizeLiteralValue;
-    private collectInverseReferenceValues;
+    private collectInverseLinkValues;
     private groupRowsByIri;
     private extractFragment;
 }
+export {};
 //# sourceMappingURL=pod-database.d.ts.map

package/dist/core/pod-database.d.ts.map

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

package/dist/core/pod-database.js

@@ -40,6 +40,15 @@ const schema_1 = require("./schema");
 const query_conditions_1 = require("./query-conditions");
 const notifications_1 = require("./notifications");
 const federated_1 = require("./federated");
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isPodTable(value) {
+    return isRecord(value) && 'columns' in value && 'config' in value;
+}
+function hasStringValue(value) {
+    return isRecord(value) && typeof value.value === 'string';
+}
 class PodDatabase {
     constructor(dialect, session, schema) {
         this.dialect = dialect;
@@ -124,9 +133,9 @@ class PodDatabase {
         if (options.hooks) {
             table.config.hooks = options.hooks;
         }
-        // Store reference to db in table for hook context
+        // Store db handle in table for hook context
         // This allows hooks to access db when invoked
-        table._db = this;
+        Reflect.set(table, '_db', this);
         return table;
     }
     // SELECT 查询
@@ -173,6 +182,42 @@ class PodDatabase {
         const rows = await builder;
         return rows.length > 0 ? rows[0] : null;
     }
+    getLocatorTemplate(table) {
+        return table.getSubjectTemplate?.() ?? table.config?.subjectTemplate ?? '{id}';
+    }
+    getRequiredLocatorKeys(table) {
+        const template = this.getLocatorTemplate(table);
+        const keys = Array.from(template.matchAll(/\{([^}]+)\}/g))
+            .map((match) => match[1])
+            .filter((key) => key !== 'index');
+        return Array.from(new Set(keys));
+    }
+    resolveLocatorSubject(table, locator, methodName) {
+        if (!isRecord(locator) || Array.isArray(locator)) {
+            throw new Error(`${methodName} requires a locator object`);
+        }
+        if ('@id' in locator) {
+            throw new Error(`${methodName} does not accept '@id'. Use ${methodName.replace('Locator', 'Iri')}(table, iri) instead.`);
+        }
+        const idValue = locator.id;
+        if (typeof idValue === 'string' && (idValue.startsWith('http://') || idValue.startsWith('https://'))) {
+            throw new Error(`${methodName} does not accept a full IRI in locator.id. Use ${methodName.replace('Locator', 'Iri')}(table, iri) instead.`);
+        }
+        const requiredKeys = this.getRequiredLocatorKeys(table);
+        const missingKeys = requiredKeys.filter((key) => locator[key] === undefined || locator[key] === null);
+        if (missingKeys.length > 0) {
+            const template = this.getLocatorTemplate(table);
+            throw new Error(`${methodName} requires a complete locator for subjectTemplate '${template}'. ` +
+                `Missing [${missingKeys.join(', ')}]. ` +
+                `Use ${methodName.replace('Locator', 'Iri')}(table, iri) when you already have a full IRI.`);
+        }
+        const resolver = this.dialect.getResolver(table);
+        return resolver.resolveSubject(table, locator);
+    }
+    async findByLocator(table, locator) {
+        const iri = this.resolveLocatorSubject(table, locator, 'findByLocator');
+        return await this.findByIri(table, iri);
+    }
     /**
      * 通过完整 IRI 查询单个实体
      *
@@ -196,14 +241,11 @@ class PodDatabase {
         if (!iri || typeof iri !== 'string') {
             throw new Error('findByIri requires a valid IRI string');
         }
-        // 解析文档 URL（去掉 fragment）
-        const { documentUrl } = this.parseIri(iri);
-        // 用 schema.table(documentUrl) 创建指向目标位置的表
-        const targetTable = table.$schema.table('target', { base: documentUrl });
-        // 使用 whereByIri 内部方法
+        // 保持原始表上下文，让 subjectTemplate/base 反解保持一致。
+        // whereByIri() 已经会把 SELECT 精确定位到目标资源，不需要把表重绑到具体文档。
         const rows = await this.session
             .select()
-            .from(targetTable)
+            .from(table)
             .whereByIri(iri)
             .limit(1);
         return (rows[0] ?? null);
@@ -318,18 +360,19 @@ class PodDatabase {
         if (!iri.startsWith('http://') && !iri.startsWith('https://')) {
             throw new Error(`updateByIri requires an absolute IRI, got: ${iri}`);
         }
-        // 解析文档 URL
-        const { documentUrl } = this.parseIri(iri);
-        // 用 schema.table(documentUrl) 创建指向目标位置的表
-        const targetTable = table.$schema.table('target', { base: documentUrl });
+        const updateData = data;
         // 使用 whereByIri 内部方法进行更新
         await this.session
-            .update(targetTable)
-            .set(data)
+            .update(table)
+            .set(updateData)
             .whereByIri(iri);
         // 返回更新后的数据
         return await this.findByIri(table, iri);
     }
+    async updateByLocator(table, locator, data) {
+        const iri = this.resolveLocatorSubject(table, locator, 'updateByLocator');
+        return await this.updateByIri(table, iri, data);
+    }
     /**
      * 通过完整 IRI 删除单个实体
      *
@@ -357,16 +400,16 @@ class PodDatabase {
         if (!existing) {
             return false;
         }
-        // 解析文档 URL
-        const { documentUrl } = this.parseIri(iri);
-        // 用 schema.table(documentUrl) 创建指向目标位置的表
-        const targetTable = table.$schema.table('target', { base: documentUrl });
         // 使用 whereByIri 内部方法进行删除
         await this.session
-            .delete(targetTable)
+            .delete(table)
             .whereByIri(iri);
         return true;
     }
+    async deleteByLocator(table, locator) {
+        const iri = this.resolveLocatorSubject(table, locator, 'deleteByLocator');
+        return await this.deleteByIri(table, iri);
+    }
     // 事务支持
     async transaction(transaction) {
         return await this.session.transaction(async (txSession) => {
@@ -866,7 +909,7 @@ class PodDatabase {
             : [];
         const tableMap = new Map();
         for (const [key, value] of schemaEntries) {
-            if (value && typeof value === 'object' && 'columns' in value) {
+            if (isPodTable(value)) {
                 tableMap.set(key, value);
             }
         }
@@ -933,39 +976,54 @@ class PodDatabase {
                 if (options?.with && Object.keys(options.with).length > 0) {
                     rows = await this.eagerLoadWith(rows, table, options.with, tableMap);
                 }
-                if (options?.columns) {
-                    rows = rows.map((row) => projectColumns(row, options.columns, options.with));
+                const columns = options?.columns;
+                if (columns) {
+                    rows = rows.map((row) => projectColumns(row, columns, options.with));
                 }
                 return rows;
             };
             const findMany = (options) => createLazy(() => executeFindMany(options));
+            const applyExactOptions = async (row, options) => {
+                if (!row) {
+                    return null;
+                }
+                let rows = [row];
+                if (options?.with && Object.keys(options.with).length > 0) {
+                    rows = await this.eagerLoadWith(rows, table, options.with, tableMap);
+                }
+                const columns = options?.columns;
+                if (columns) {
+                    rows = rows.map((item) => projectColumns(item, columns, options.with));
+                }
+                return (rows[0] ?? null);
+            };
             const findFirst = (options) => createLazy(async () => {
                 const rows = await executeFindMany({ ...options, limit: 1 });
                 return rows[0] ?? null;
             });
-            const findById = (id, options) => createLazy(async () => await findFirst({ ...options, where: { ...(options?.where ?? {}), id } }));
             const count = (options) => createLazy(async () => {
                 const rows = await executeFindMany({ where: options?.where, columns: undefined, limit: undefined, offset: undefined });
                 return rows.length;
             });
-            const createFindByIRI = () => (iri, _options) => {
-                void _options;
-                return createLazy(async () => await this.findByIri(table, iri));
-            };
+            const createFindByLocator = () => (locator, options) => createLazy(async () => await applyExactOptions(await this.findByLocator(table, locator), options));
+            const createFindByIri = () => (iri, options) => createLazy(async () => await applyExactOptions(await this.findByIri(table, iri), options));
             return {
                 findMany,
                 findFirst,
-                findById,
-                /** @deprecated Use db.findByIri(table, iri) instead */
-                findByIRI: createFindByIRI(),
+                findByLocator: createFindByLocator(),
+                findByIri: createFindByIri(),
                 count
             };
         };
         const proxyTarget = {};
         return new Proxy(proxyTarget, {
             get: (_, prop) => {
-                if (tableMap.has(prop)) {
-                    return createHelper(prop, tableMap.get(prop));
+                if (typeof prop !== 'string') {
+                    return undefined;
+                }
+                const table = tableMap.get(prop);
+                if (table) {
+                    return createHelper(prop, table);
                 }
                 return undefined;
             }
@@ -1022,29 +1080,29 @@ class PodDatabase {
             const candidateColumns = relationDef?.fields && relationDef.fields.length > 0
                 ? relationDef.fields
                 : Object.values(targetPodTable.columns ?? {});
-            const matchesParentReference = (col) => Boolean(col && (col.options?.referenceTarget === parentTable.config.type ||
-                col.options?.referenceTable === parentTable ||
-                col.getReferenceTable?.() === parentTable));
-            const matchesTargetReference = (col) => Boolean(col && (col.options?.referenceTarget === targetType ||
-                col.options?.referenceTable === targetPodTable ||
-                col.getReferenceTable?.() === targetPodTable));
-            const referenceColumns = relationDef?.fields && relationDef.fields.length > 0
+            const matchesParentLink = (col) => Boolean(col && (col.options?.linkTarget === parentTable.config.type ||
+                col.options?.linkTable === parentTable ||
+                col.getLinkTable?.() === parentTable));
+            const matchesTargetLink = (col) => Boolean(col && (col.options?.linkTarget === targetType ||
+                col.options?.linkTable === targetPodTable ||
+                col.getLinkTable?.() === targetPodTable));
+            const linkColumns = relationDef?.fields && relationDef.fields.length > 0
                 ? candidateColumns
-                : candidateColumns.filter((col) => matchesParentReference(col) && !col.isInverse?.());
-            if (referenceColumns.length === 0) {
-                const relationReferences = relationDef?.references ?? [];
-                const explicitInverse = relationReferences.filter((col) => Boolean(col &&
+                : candidateColumns.filter((col) => matchesParentLink(col) && !col.isInverse?.());
+            if (linkColumns.length === 0) {
+                const relationReferenceFields = relationDef?.references ?? [];
+                const explicitInverse = relationReferenceFields.filter((col) => Boolean(col &&
                     typeof col.isInverse === 'function' &&
                     col.isInverse() &&
-                    matchesTargetReference(col)));
+                    matchesTargetLink(col)));
                 const parentColumns = Object.values(parentTable.columns ?? {});
                 const inverseCandidates = (explicitInverse.length > 0 ? explicitInverse : parentColumns).filter((col) => typeof col.isInverse === 'function' &&
                     col.isInverse() &&
-                    matchesTargetReference(col));
+                    matchesTargetLink(col));
                 if (inverseCandidates.length === 0) {
                     continue;
                 }
-                const inverseValuesPerRow = dedupedRows.map((row) => this.collectInverseReferenceValues(row, inverseCandidates));
+                const inverseValuesPerRow = dedupedRows.map((row) => this.collectInverseLinkValues(row, inverseCandidates));
                 const uniqueIris = Array.from(new Set(inverseValuesPerRow
                     .flat()
                     .filter((iri) => typeof iri === 'string' && iri.length > 0)));
@@ -1071,17 +1129,17 @@ class PodDatabase {
                 });
                 continue;
             }
-            const refColumn = referenceColumns[0];
-            const referenceColumn = relationDef?.references && relationDef.references[0];
-            const useReferenceIri = refColumn.isReference();
+            const refColumn = linkColumns[0];
+            const linkColumn = relationDef?.references && relationDef.references[0];
+            const useLinkIri = refColumn.isLink();
             const parentKeys = dedupedRows
-                .map((row) => this.resolveParentKey(row, referenceColumn, useReferenceIri))
+                .map((row) => this.resolveParentKey(row, linkColumn, useLinkIri))
                 .filter((value) => typeof value === 'string' && value.length > 0);
             if (parentKeys.length === 0) {
                 continue;
             }
             let childBuilder = this.session.select().from(targetPodTable);
-            if (useReferenceIri) {
+            if (useLinkIri) {
                 childBuilder = childBuilder.where((0, query_conditions_1.inArray)(refColumn, parentKeys));
             }
             else {
@@ -1091,9 +1149,10 @@ class PodDatabase {
             const grouped = new Map();
             for (const child of childRows) {
                 const fkValue = child[refColumn.name];
-                const lookupKeys = useReferenceIri
-                    ? this.collectReferenceLookupKeys(fkValue)
-                    : (this.normalizeLiteralValue(fkValue) ? [this.normalizeLiteralValue(fkValue)] : []);
+                const normalizedFkValue = this.normalizeLiteralValue(fkValue);
+                const lookupKeys = useLinkIri
+                    ? this.collectLinkLookupKeys(fkValue)
+                    : (normalizedFkValue ? [normalizedFkValue] : []);
                 for (const lookupKey of lookupKeys) {
                     const arr = grouped.get(lookupKey) ?? [];
                     arr.push(child);
@@ -1101,12 +1160,12 @@ class PodDatabase {
                 }
             }
             dedupedRows.forEach((row) => {
-                const parentKeys = useReferenceIri
+                const parentKeys = useLinkIri
                     ? Array.from(new Set([
-                        this.resolveParentKey(row, referenceColumn, true),
+                        this.resolveParentKey(row, linkColumn, true),
                         this.resolveIdFromRow(row),
                     ].filter((value) => typeof value === 'string' && value.length > 0)))
-                    : [this.resolveParentKey(row, referenceColumn, false)].filter((value) => typeof value === 'string' && value.length > 0);
+                    : [this.resolveParentKey(row, linkColumn, false)].filter((value) => typeof value === 'string' && value.length > 0);
                 const related = [];
                 for (const parentKey of parentKeys) {
                     const matches = grouped.get(parentKey) ?? [];
@@ -1137,6 +1196,9 @@ class PodDatabase {
                 continue;
             }
             const target = merged.get(key);
+            if (!target) {
+                continue;
+            }
             for (const [col, value] of Object.entries(row)) {
                 if (value === undefined)
                     continue;
@@ -1156,7 +1218,9 @@ class PodDatabase {
                 target[col] = mergedArr.length === 1 ? mergedArr[0] : mergedArr;
             }
         }
-        return order.map((key) => merged.get(key));
+        return order
+            .map((key) => merged.get(key))
+            .filter((row) => row !== undefined);
     }
     resolveIdFromRow(row) {
         if (!row)
@@ -1170,12 +1234,12 @@ class PodDatabase {
         }
         return undefined;
     }
-    resolveParentKey(row, referenceColumn, useReferenceIri) {
-        if (referenceColumn) {
-            const value = row[referenceColumn.name];
-            return useReferenceIri ? this.normalizeReferenceValue(value) : this.normalizeLiteralValue(value);
+    resolveParentKey(row, linkColumn, useLinkIri) {
+        if (linkColumn) {
+            const value = row[linkColumn.name];
+            return useLinkIri ? this.normalizeLinkValue(value) : this.normalizeLiteralValue(value);
         }
-        return useReferenceIri ? this.resolveIriFromRow(row) : this.resolveIdFromRow(row);
+        return useLinkIri ? this.resolveIriFromRow(row) : this.resolveIdFromRow(row);
     }
     resolveIriFromRow(row) {
         if (!row)
@@ -1188,9 +1252,9 @@ class PodDatabase {
         }
         return undefined;
     }
-    collectReferenceLookupKeys(value) {
+    collectLinkLookupKeys(value) {
         const keys = [];
-        const normalized = this.normalizeReferenceValue(value) ?? this.normalizeLiteralValue(value);
+        const normalized = this.normalizeLinkValue(value) ?? this.normalizeLiteralValue(value);
         if (normalized) {
             keys.push(normalized);
             const fragment = this.extractFragment(normalized);
@@ -1200,13 +1264,13 @@ class PodDatabase {
         }
         return keys;
     }
-    normalizeReferenceValue(value) {
+    normalizeLinkValue(value) {
         if (!value)
             return undefined;
         if (typeof value === 'string') {
             return value;
         }
-        if (typeof value === 'object' && typeof value.value === 'string') {
+        if (hasStringValue(value)) {
             return value.value;
         }
         return undefined;
@@ -1218,12 +1282,12 @@ class PodDatabase {
         if (typeof value === 'string') {
             return value;
         }
-        if (typeof value === 'object' && typeof value.value === 'string') {
+        if (hasStringValue(value)) {
             return value.value;
         }
         return undefined;
     }
-    collectInverseReferenceValues(row, columns) {
+    collectInverseLinkValues(row, columns) {
         if (!columns.length) {
             return [];
         }
@@ -1234,7 +1298,7 @@ class PodDatabase {
                 continue;
             }
             const appendValue = (entry) => {
-                const normalized = this.normalizeReferenceValue(entry) ?? (typeof entry === 'string' ? entry : undefined);
+                const normalized = this.normalizeLinkValue(entry) ?? (typeof entry === 'string' ? entry : undefined);
                 if (normalized) {
                     collected.push(normalized);
                 }
@@ -1251,8 +1315,8 @@ class PodDatabase {
     groupRowsByIri(rows) {
         const grouped = new Map();
         for (const row of rows) {
-            const iri = this.normalizeReferenceValue(row['@id']) ??
-                this.normalizeReferenceValue(row.uri) ??
+            const iri = this.normalizeLinkValue(row['@id']) ??
+                this.normalizeLinkValue(row.uri) ??
                 (typeof row['@id'] === 'string' ? row['@id'] : undefined);
             if (!iri) {
                 continue;