@undefineds.co/xpod 0.2.45 → 0.3.1

package/node_modules/@undefineds.co/drizzle-solid/dist/esm/core/pod-database.js

@@ -5,6 +5,7 @@ import { inArray } from './query-conditions.js';
 import { NotificationsClient } from './notifications/index.js';
 import { FederatedQueryExecutor } from './federated/index.js';
 import { parsePodResourceRef } from './resource-reference.js';
+import { Parser } from 'n3';
 function isRecord(value) {
     return typeof value === 'object' && value !== null;
 }
@@ -22,7 +23,6 @@ function isBaseRelativeSubjectId(value) {
         return false;
     }
     return (value.startsWith('#') ||
-        value.includes('/') ||
         value.includes('#') ||
         /\.(ttl|jsonld|json)(?:#|$)/i.test(value));
 }
@@ -32,6 +32,13 @@ function isTimeLocatorKey(key) {
 function parseTemplateVariableField(token) {
     return token.split('|').map((part) => part.trim()).filter(Boolean)[0] ?? token;
 }
+function escapeSparqlString(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r');
+}
 function hasTimeLocatorContext(locator) {
     return locator.createdAt !== undefined
         || locator.created_at !== undefined
@@ -180,21 +187,24 @@ export class PodDatabase {
         return rows.length > 0 ? rows[0] : null;
     }
     getLocatorTemplate(table) {
-        return table.getSubjectTemplate?.() ?? table.config?.subjectTemplate ?? '{id}';
+        return table.getSubjectTemplate?.() ?? table.config?.subjectTemplate;
     }
     getRequiredLocatorKeys(table) {
         const template = this.getLocatorTemplate(table);
+        if (!template) {
+            return ['id'];
+        }
         const keys = Array.from(template.matchAll(/\{([^}]+)\}/g))
             .map((match) => parseTemplateVariableField(match[1]))
             .filter((key) => key !== 'index');
         return Array.from(new Set(keys));
     }
-    resolveResourceTargetIri(table, target, methodName) {
+    resolveResourceTargetIri(resource, target, methodName) {
         if (typeof target === 'string') {
             if (isAbsoluteIri(target)) {
                 return target;
             }
-            return this.resolveLocatorSubject(table, { id: target }, methodName);
+            return this.resolveLocatorSubject(resource, { id: target }, methodName);
         }
         if (!isRecord(target) || Array.isArray(target)) {
             throw new Error(`${methodName} requires a resource IRI, base-relative id, row, or locator object`);
@@ -203,9 +213,9 @@ export class PodDatabase {
         if (knownIri) {
             return knownIri;
         }
-        return this.resolveLocatorSubject(table, target, methodName);
+        return this.resolveLocatorSubject(resource, target, methodName);
     }
-    resolveLocatorSubject(table, locator, methodName) {
+    resolveLocatorSubject(resource, locator, methodName) {
         if (!isRecord(locator) || Array.isArray(locator)) {
             throw new Error(`${methodName} requires a locator object`);
         }
@@ -216,11 +226,8 @@ export class PodDatabase {
         if (typeof idValue === 'string' && isAbsoluteIri(idValue)) {
             throw new Error(`${methodName} does not accept a full IRI in locator.id. Use ${this.getIriAlternative(methodName)} instead.`);
         }
-        const resolver = this.dialect.getResolver(table);
-        if (typeof idValue === 'string' && isBaseRelativeSubjectId(idValue)) {
-            return resolver.resolveSubject(table, locator);
-        }
-        const requiredKeys = this.getRequiredLocatorKeys(table);
+        const requiredKeys = this.getRequiredLocatorKeys(resource);
+        const resolver = this.dialect.getResolver(resource);
         const hasTimeContext = hasTimeLocatorContext(locator);
         const missingKeys = requiredKeys.filter((key) => {
             if (locator[key] !== undefined && locator[key] !== null) {
@@ -228,112 +235,392 @@ export class PodDatabase {
             }
             return !(hasTimeContext && isTimeLocatorKey(key));
         });
+        if (typeof idValue === 'string' && isBaseRelativeSubjectId(idValue)) {
+            const nonIdRequiredKeys = requiredKeys.filter((key) => key !== 'id');
+            if (idValue.startsWith('#') && nonIdRequiredKeys.length > 0) {
+                const template = this.getLocatorTemplate(resource) ?? '<exact-id>';
+                throw new Error(`${methodName} requires a complete locator for subjectTemplate '${template}'. ` +
+                    `Missing [${nonIdRequiredKeys.join(', ')}]. ` +
+                    `Use a base-relative resource id that includes every storage slot.`);
+            }
+            return resolver.resolveSubject(resource, locator);
+        }
         if (missingKeys.length > 0) {
-            const template = this.getLocatorTemplate(table);
+            const template = this.getLocatorTemplate(resource) ?? '<exact-id>';
             throw new Error(`${methodName} requires a complete locator for subjectTemplate '${template}'. ` +
                 `Missing [${missingKeys.join(', ')}]. ` +
                 `Use ${this.getIriAlternative(methodName)} when you already have a full IRI.`);
         }
-        return resolver.resolveSubject(table, locator);
+        return resolver.resolveSubject(resource, locator);
+    }
+    resolveIdSubject(resource, id, methodName) {
+        if (!id || typeof id !== 'string') {
+            throw new Error(`${methodName} requires a valid base-relative resource id string`);
+        }
+        if (isAbsoluteIri(id)) {
+            throw new Error(`${methodName} requires a base-relative resource id. Use ${this.getIriAlternative(methodName)} for full IRIs.`);
+        }
+        const template = this.getLocatorTemplate(resource) ?? '<exact-id>';
+        const missingNonIdKeys = this.getRequiredLocatorKeys(resource).filter((key) => key !== 'id');
+        const resolver = this.dialect.getResolver(resource);
+        if (isBaseRelativeSubjectId(id)) {
+            if (id.startsWith('#') && missingNonIdKeys.length > 0) {
+                throw new Error(`${methodName} requires a base-relative resource id for subjectTemplate '${template}', got local fragment id '${id}'. ` +
+                    `Missing [${missingNonIdKeys.join(', ')}]. ` +
+                    `Use a base-relative id that includes every storage slot.`);
+            }
+            return resolver.resolveSubject(resource, { id: id.startsWith('#') ? id.slice(1) : id });
+        }
+        if (missingNonIdKeys.length > 0) {
+            throw new Error(`${methodName} requires a base-relative resource id for subjectTemplate '${template}', got local id '${id}'. ` +
+                `Missing [${missingNonIdKeys.join(', ')}]. ` +
+                `Use a base-relative id that includes every storage slot.`);
+        }
+        return resolver.resolveSubject(resource, { id });
+    }
+    warnFindByLocatorDeprecation() {
+        if (PodDatabase.findByLocatorDeprecationWarned) {
+            return;
+        }
+        PodDatabase.findByLocatorDeprecationWarned = true;
+        console.warn('[drizzle-solid] findByLocator(resource, locator) is deprecated and will be removed in a future release. ' +
+            'Use findById(resource, id) for base-relative resource ids, findByResource(resource, target) for generic exact targets, ' +
+            'or findByIri(resource, iri) for full IRIs.');
     }
     getIriAlternative(methodName) {
         if (methodName === 'resolveLocatorIri' || methodName === 'resolveLocatorId') {
             return 'the full IRI directly';
         }
-        if (methodName === 'findByResource') {
-            return 'findByIri(table, iri)';
+        if (methodName === 'findById' || methodName === 'findByResource') {
+            return 'findByIri(resource, iri)';
         }
-        if (methodName === 'updateByResource') {
-            return 'updateByIri(table, iri, data)';
+        if (methodName === 'updateById' || methodName === 'updateByResource') {
+            return 'updateByIri(resource, iri, data)';
         }
-        if (methodName === 'deleteByResource') {
-            return 'deleteByIri(table, iri)';
+        if (methodName === 'deleteById' || methodName === 'deleteByResource') {
+            return 'deleteByIri(resource, iri)';
         }
-        return `${methodName.replace('Locator', 'Iri')}(table, iri)`;
+        return `${methodName.replace('Locator', 'Iri')}(resource, iri)`;
     }
-    resolveLocatorIri(table, locator) {
-        return this.resolveLocatorSubject(table, locator, 'resolveLocatorIri');
+    resolveLocatorIri(resource, locator) {
+        return this.resolveLocatorSubject(resource, locator, 'resolveLocatorIri');
     }
-    resolveLocatorId(table, locator) {
-        const iri = this.resolveLocatorSubject(table, locator, 'resolveLocatorId');
-        return this.dialect.getResolver(table).parseId(table, iri);
+    resolveLocatorId(resource, locator) {
+        const iri = this.resolveLocatorSubject(resource, locator, 'resolveLocatorId');
+        return this.resolveBaseRelativeResourceId(resource, iri);
     }
-    resolveResourceIri(table, target) {
-        return this.resolveResourceTargetIri(table, target, 'resolveResourceIri');
+    resolveResourceIri(resource, target) {
+        return this.resolveResourceTargetIri(resource, target, 'resolveResourceIri');
     }
-    resolveResourceId(table, target) {
-        const iri = this.resolveResourceTargetIri(table, target, 'resolveResourceId');
-        return parsePodResourceRef(table, iri)?.resourceId ?? this.dialect.getResolver(table).parseId(table, iri);
+    resolveResourceId(resource, target) {
+        const iri = this.resolveResourceTargetIri(resource, target, 'resolveResourceId');
+        return this.resolveBaseRelativeResourceId(resource, iri);
     }
-    resolveRelationIri(table, target) {
-        return this.resolveResourceTargetIri(table, target, 'resolveRelationIri');
+    resolveRelationIri(resource, target) {
+        return this.resolveResourceTargetIri(resource, target, 'resolveRelationIri');
     }
-    resolveRowIri(table, row) {
+    resolveRowIri(resource, row) {
         if (!isRecord(row) || Array.isArray(row)) {
             throw new Error('resolveRowIri requires a row object');
         }
-        return getKnownRowIri(row) ?? this.resolveLocatorSubject(table, row, 'resolveRowIri');
+        return getKnownRowIri(row) ?? this.resolveLocatorSubject(resource, row, 'resolveRowIri');
     }
-    resolveRowId(table, row) {
+    resolveRowId(resource, row) {
         if (!isRecord(row) || Array.isArray(row)) {
             throw new Error('resolveRowId requires a row object');
         }
-        const iri = getKnownRowIri(row) ?? this.resolveLocatorSubject(table, row, 'resolveRowId');
-        return this.dialect.getResolver(table).parseId(table, iri);
+        const iri = getKnownRowIri(row) ?? this.resolveLocatorSubject(resource, row, 'resolveRowId');
+        return this.resolveBaseRelativeResourceId(resource, iri);
+    }
+    resolveBaseRelativeResourceId(resource, iri) {
+        return parsePodResourceRef(resource, iri)?.resourceId ?? this.dialect.getResolver(resource).parseId(resource, iri);
     }
-    async findByLocator(table, locator) {
-        const iri = this.resolveLocatorSubject(table, locator, 'findByLocator');
-        return await this.findByIri(table, iri);
+    needsShortIdSubjectLookup(resource, id) {
+        if (!id || typeof id !== 'string' || isAbsoluteIri(id) || isBaseRelativeSubjectId(id)) {
+            return false;
+        }
+        return this.getRequiredLocatorKeys(resource).some((key) => key !== 'id');
     }
-    async findByResource(table, target) {
-        const iri = this.resolveResourceTargetIri(table, target, 'findByResource');
-        return await this.findByIri(table, iri);
+    buildShortIdSubjectSuffix(resource, id) {
+        const template = this.getLocatorTemplate(resource) ?? '<exact-id>';
+        const matches = Array.from(template.matchAll(/\{([^}]+)\}/g));
+        let idMatchIndex = -1;
+        for (let index = matches.length - 1; index >= 0; index--) {
+            if (parseTemplateVariableField(matches[index][1]) === 'id') {
+                idMatchIndex = index;
+                break;
+            }
+        }
+        if (idMatchIndex < 0) {
+            return id;
+        }
+        const idMatch = matches[idMatchIndex];
+        const previousMatch = matches[idMatchIndex - 1];
+        const previousEnd = previousMatch?.index === undefined
+            ? 0
+            : previousMatch.index + previousMatch[0].length;
+        const idStart = idMatch.index ?? 0;
+        const idEnd = idStart + idMatch[0].length;
+        return `${template.slice(previousEnd, idStart)}${id}${template.slice(idEnd)}`;
+    }
+    resolveShortIdLookupSource(resource) {
+        const dialectWithResolver = this.dialect;
+        if (typeof dialectWithResolver.resolveTableResource === 'function') {
+            const descriptor = dialectWithResolver.resolveTableResource(resource);
+            if (descriptor.mode === 'sparql' && descriptor.endpoint) {
+                return { kind: 'sparql', resourceUrl: descriptor.endpoint, descriptor };
+            }
+        }
+        return null;
     }
-    async findByIri(table, iri) {
+    extractSubjectFromLookupRow(row) {
+        if (!isRecord(row)) {
+            return null;
+        }
+        const value = row.subject ?? row.s ?? row['?subject'] ?? row['?s'];
+        if (typeof value === 'string') {
+            return value;
+        }
+        if (hasStringValue(value)) {
+            return value.value;
+        }
+        return null;
+    }
+    subjectMatchesShortId(resource, subject, id, suffix) {
+        const ref = parsePodResourceRef(resource, subject);
+        if (ref) {
+            return ref.templateValues.id === id;
+        }
+        return subject.endsWith(suffix);
+    }
+    getIndexedSubject(resource, id) {
+        const dialect = this.dialect;
+        if (typeof dialect.lookupIndexedResourceSubject !== 'function') {
+            return null;
+        }
+        return dialect.lookupIndexedResourceSubject(resource, id);
+    }
+    async lookupSubjectIriByShortId(resource, id, methodName) {
+        const source = this.resolveShortIdLookupSource(resource);
+        if (!source) {
+            const template = this.getLocatorTemplate(resource) ?? '<exact-id>';
+            throw new Error(`${methodName} cannot resolve short id '${id}' for subjectTemplate '${template}' ` +
+                `because no resource query source is available.`);
+        }
+        const suffix = this.buildShortIdSubjectSuffix(resource, id);
+        const containsNeedle = id;
+        const matchClause = resource.config?.type
+            ? `?subject ?typePredicate ?typeObject .
+    FILTER(?typePredicate = <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> && ?typeObject = <${resource.config.type}> && CONTAINS(STR(?subject), "${escapeSparqlString(containsNeedle)}"))`
+            : `?subject ?predicate ?object .
+    FILTER(CONTAINS(STR(?subject), "${escapeSparqlString(containsNeedle)}"))`;
+        const query = {
+            type: 'SELECT',
+            query: `SELECT DISTINCT ?subject WHERE {
+  ${matchClause}
+}
+LIMIT 50`,
+            prefixes: {},
+        };
+        const rows = source.kind === 'sparql'
+            ? await this.dialect.executeOnResource(source.resourceUrl, query, source.descriptor)
+            : await this.dialect.getSPARQLExecutor().queryContainer(source.resourceUrl, query);
+        const subjects = Array.from(new Set(rows
+            .map((row) => this.extractSubjectFromLookupRow(row))
+            .filter((value) => Boolean(value))
+            .filter((value) => this.subjectMatchesShortId(resource, value, id, suffix))));
+        if (subjects.length > 1) {
+            throw new Error(`${methodName} found multiple resources for short id '${id}' in '${resource.config?.name ?? 'resource'}'. ` +
+                `Use a base-relative resource id or full IRI to disambiguate.`);
+        }
+        return subjects[0] ?? this.getIndexedSubject(resource, id);
+    }
+    async resolveIdSubjectForExactOperation(resource, id, methodName) {
+        if (this.needsShortIdSubjectLookup(resource, id)) {
+            return await this.lookupSubjectIriByShortId(resource, id, methodName);
+        }
+        return this.resolveIdSubject(resource, id, methodName);
+    }
+    async findById(resource, id) {
+        const iri = await this.resolveIdSubjectForExactOperation(resource, id, 'findById');
+        if (!iri) {
+            return null;
+        }
+        return await this.findByIri(resource, iri);
+    }
+    async findByLocator(resource, locator) {
+        this.warnFindByLocatorDeprecation();
+        const iri = this.resolveLocatorSubject(resource, locator, 'findByLocator');
+        return await this.findByIri(resource, iri);
+    }
+    async findByResource(resource, target) {
+        if (typeof target === 'string' && this.needsShortIdSubjectLookup(resource, target)) {
+            return await this.findById(resource, target);
+        }
+        const iri = this.resolveResourceTargetIri(resource, target, 'findByResource');
+        return await this.findByIri(resource, iri);
+    }
+    async findByIri(resource, iri) {
         if (!iri || typeof iri !== 'string') {
             throw new Error('findByIri requires a valid IRI string');
         }
-        const exactRead = await this.findByIriViaExactSparql(table, iri);
+        const exactRead = await this.findByIriViaExactResource(resource, iri);
         if (exactRead !== undefined) {
             return exactRead;
         }
-        // 保持原始表上下文，让 subjectTemplate/base 反解保持一致。
-        // whereByIri() 已经会把 SELECT 精确定位到目标资源，不需要把表重绑到具体文档。
+        // Keep the original resource context so subjectTemplate/base decoding stays stable.
+        // whereByIri() already pins SELECT to the concrete resource IRI.
         const rows = await this.session
             .select()
-            .from(table)
+            .from(resource)
             .whereByIri(iri)
             .limit(1);
         return rows[0] ?? null;
     }
-    getColumnPredicate(table, column) {
-        return column.options?.predicate ?? column.getPredicate?.(table.config.namespace);
+    getColumnPredicate(resource, column) {
+        return column.options?.predicate ?? column.getPredicate?.(resource.config.namespace);
     }
-    async findByIriViaExactSparql(table, iri) {
-        if (!isPodTable(table)) {
+    async findByIriViaExactResource(resource, iri) {
+        if (!isPodTable(resource)) {
             return undefined;
         }
-        if (typeof this.dialect.resolveTableResource !== 'function'
-            || typeof this.dialect.executeOnResource !== 'function') {
+        const documentUrl = this.parseIri(iri).documentUrl;
+        const directRows = await this.readPredicateObjectRowsFromDocument(documentUrl, iri);
+        if (directRows === null) {
+            return null;
+        }
+        if (directRows !== undefined) {
+            const mapped = this.mapPredicateObjectRows(resource, iri, directRows);
+            if (mapped !== undefined) {
+                return mapped;
+            }
+        }
+        if (typeof this.dialect.executeOnResource !== 'function') {
             return undefined;
         }
-        const documentUrl = this.parseIri(iri).documentUrl;
-        const descriptor = this.dialect.resolveTableResource(table);
         const query = {
             type: 'SELECT',
             query: `SELECT ?p ?o WHERE { <${iri}> ?p ?o . }`,
             prefixes: {}
         };
-        const rows = descriptor.mode === 'sparql'
-            ? await this.dialect.executeOnResource(documentUrl, query, descriptor)
-            : await this.dialect.executeOnResource(documentUrl, query);
-        const mapped = this.mapPredicateObjectRows(table, iri, rows);
-        if (mapped) {
+        // Exact-target reads already know the concrete Pod document. Do not route
+        // through a collection sidecar SPARQL endpoint such as /.data/chat/-/sparql.
+        let rows;
+        try {
+            rows = await this.dialect.executeOnResource(documentUrl, query);
+        }
+        catch (error) {
+            if (this.isMissingExactResourceError(error)) {
+                return undefined;
+            }
+            throw error;
+        }
+        const mapped = this.mapPredicateObjectRows(resource, iri, rows);
+        if (mapped !== undefined) {
             return mapped;
         }
-        return null;
+        return undefined;
+    }
+    async readPredicateObjectRowsFromDocument(documentUrl, iri) {
+        const getAuthenticatedFetch = this.dialect.getAuthenticatedFetch;
+        if (typeof getAuthenticatedFetch !== 'function') {
+            return undefined;
+        }
+        let response;
+        try {
+            response = await getAuthenticatedFetch.call(this.dialect)(documentUrl, {
+                method: 'GET',
+                headers: {
+                    Accept: 'text/turtle, application/ld+json;q=0.8, */*;q=0.1',
+                },
+            });
+        }
+        catch (error) {
+            if (this.isMissingExactResourceError(error)) {
+                return null;
+            }
+            return undefined;
+        }
+        if (response.status === 404) {
+            return null;
+        }
+        if (!response.ok) {
+            return undefined;
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (contentType
+            && !contentType.includes('text/turtle')
+            && !contentType.includes('application/n-triples')
+            && !contentType.includes('application/trig')
+            && !contentType.includes('application/ld+json')) {
+            return undefined;
+        }
+        const body = await response.text();
+        if (!body.trim()) {
+            return null;
+        }
+        try {
+            const parser = new Parser({
+                baseIRI: documentUrl,
+                format: contentType.includes('application/n-triples') ? 'N-Triples' : 'text/turtle',
+            });
+            const quads = parser.parse(body);
+            return quads
+                .filter((quad) => quad.subject.termType === 'NamedNode' && quad.subject.value === iri)
+                .map((quad) => ({
+                p: quad.predicate.value,
+                o: this.convertRdfTermToValue(quad.object),
+            }));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    convertRdfTermToValue(term) {
+        if (term.termType === 'NamedNode') {
+            return term.value;
+        }
+        if (term.termType === 'BlankNode') {
+            return `_:${term.value}`;
+        }
+        if (term.termType !== 'Literal') {
+            return term.value;
+        }
+        const datatypeIri = term.datatype?.value ?? '';
+        if (datatypeIri.includes('#integer') || datatypeIri.includes('#int')) {
+            return parseInt(term.value, 10);
+        }
+        if (datatypeIri.includes('#decimal') || datatypeIri.includes('#double')) {
+            return parseFloat(term.value);
+        }
+        if (datatypeIri.includes('#boolean')) {
+            return term.value === 'true';
+        }
+        if (datatypeIri.includes('#dateTime')) {
+            return new Date(term.value);
+        }
+        if (datatypeIri.includes('#json')) {
+            try {
+                return JSON.parse(term.value);
+            }
+            catch {
+                return term.value;
+            }
+        }
+        return term.value;
+    }
+    isMissingExactResourceError(error) {
+        if (!isRecord(error)) {
+            return false;
+        }
+        const status = error.status ?? error.statusCode;
+        if (status === 404) {
+            return true;
+        }
+        const message = error.message;
+        return typeof message === 'string' && /\b(?:HTTP status )?404\b/.test(message);
     }
-    mapPredicateObjectRows(table, iri, rows) {
+    mapPredicateObjectRows(resource, iri, rows) {
         if (!Array.isArray(rows) || rows.length === 0) {
             return null;
         }
@@ -342,12 +629,13 @@ export class PodDatabase {
             '@id': iri,
             uri: iri,
         };
-        const derivedId = this.extractIdFromIri(table, iri);
+        const derivedId = this.extractIdFromIri(resource, iri);
         if (derivedId !== undefined) {
             row.id = derivedId;
         }
         let hasType = false;
         let hasAnyMappedPredicate = false;
+        let hasUnhydratedInlineObject = false;
         for (const result of rows) {
             if (!isRecord(result)) {
                 continue;
@@ -358,14 +646,14 @@ export class PodDatabase {
                 continue;
             }
             if (predicate === 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type'
-                && object === table.config.type) {
+                && object === resource.config.type) {
                 hasType = true;
             }
-            for (const [key, column] of Object.entries(table.columns ?? {})) {
+            for (const [key, column] of Object.entries(resource.columns ?? {})) {
                 if (column._virtualId) {
                     continue;
                 }
-                const columnPredicate = this.getColumnPredicate(table, column);
+                const columnPredicate = this.getColumnPredicate(resource, column);
                 if (!columnPredicate || columnPredicate === '@id' || columnPredicate !== predicate) {
                     continue;
                 }
@@ -377,25 +665,37 @@ export class PodDatabase {
                 else if (row[key] === undefined) {
                     row[key] = object;
                 }
+                if ((column.dataType === 'object' || column.dataType === 'json')
+                    && typeof object === 'string'
+                    && isAbsoluteIri(object)) {
+                    hasUnhydratedInlineObject = true;
+                }
                 hasAnyMappedPredicate = true;
             }
         }
         if (!hasType && !hasAnyMappedPredicate) {
             return null;
         }
+        if (hasUnhydratedInlineObject) {
+            return undefined;
+        }
         return row;
     }
-    extractIdFromIri(table, iri) {
+    extractIdFromIri(resource, iri) {
+        const resourceId = parsePodResourceRef(resource, iri)?.resourceId;
+        if (resourceId) {
+            return resourceId;
+        }
         try {
-            const parsedId = this.dialect.getResolver(table).parseId(table, iri);
+            const parsedId = this.dialect.getResolver(resource).parseId(resource, iri);
             if (parsedId) {
                 return parsedId;
             }
         }
         catch {
-            // Fall through to conservative legacy parsing for non-standard tables.
+            // Fall through to conservative legacy parsing for non-standard resources.
         }
-        const template = table.getSubjectTemplate?.() ?? table.config?.subjectTemplate;
+        const template = resource.getSubjectTemplate?.() ?? resource.config?.subjectTemplate;
         if (!template) {
             return undefined;
         }
@@ -431,7 +731,7 @@ export class PodDatabase {
     /**
      * 通过完整 IRI 订阅单个实体的变更
      *
-     * @param table - 表定义
+     * @param resource - Resource definition used to decode schema and subject shape.
      * @param iri - 完整 IRI，本地或远程
      * @param options - 订阅选项
      * @returns 取消订阅函数
@@ -458,7 +758,7 @@ export class PodDatabase {
      * unsubscribe()
      * ```
      */
-    async subscribeByIri(table, iri, options) {
+    async subscribeByIri(resource, iri, options) {
         if (!iri || typeof iri !== 'string') {
             throw new Error('subscribeByIri requires a valid IRI string');
         }
@@ -483,7 +783,7 @@ export class PodDatabase {
                 try {
                     if (event.type === 'Update') {
                         // 重新获取数据
-                        const data = await this.findByIri(table, iri);
+                        const data = await this.findByIri(resource, iri);
                         if (data) {
                             await options.onUpdate(data);
                         }
@@ -501,7 +801,7 @@ export class PodDatabase {
         // 返回取消订阅函数
         return () => subscription.unsubscribe();
     }
-    async updateByIri(table, iri, data) {
+    async updateByIri(resource, iri, data) {
         if (!iri || typeof iri !== 'string') {
             throw new Error('updateByIri requires a valid IRI string');
         }
@@ -511,24 +811,34 @@ export class PodDatabase {
         const updateData = data;
         // 使用 whereByIri 内部方法进行更新
         await this.session
-            .update(table)
+            .update(resource)
             .set(updateData)
             .whereByIri(iri);
         // 返回更新后的数据
-        return await this.findByIri(table, iri);
+        return await this.findByIri(resource, iri);
+    }
+    async updateById(resource, id, data) {
+        const iri = await this.resolveIdSubjectForExactOperation(resource, id, 'updateById');
+        if (!iri) {
+            return null;
+        }
+        return await this.updateByIri(resource, iri, data);
     }
-    async updateByLocator(table, locator, data) {
-        const iri = this.resolveLocatorSubject(table, locator, 'updateByLocator');
-        return await this.updateByIri(table, iri, data);
+    async updateByLocator(resource, locator, data) {
+        const iri = this.resolveLocatorSubject(resource, locator, 'updateByLocator');
+        return await this.updateByIri(resource, iri, data);
     }
-    async updateByResource(table, target, data) {
-        const iri = this.resolveResourceTargetIri(table, target, 'updateByResource');
-        return await this.updateByIri(table, iri, data);
+    async updateByResource(resource, target, data) {
+        if (typeof target === 'string' && this.needsShortIdSubjectLookup(resource, target)) {
+            return await this.updateById(resource, target, data);
+        }
+        const iri = this.resolveResourceTargetIri(resource, target, 'updateByResource');
+        return await this.updateByIri(resource, iri, data);
     }
     /**
      * 通过完整 IRI 删除单个实体
      *
-     * @param table - 表定义
+     * @param resource - Resource definition used to decode schema and subject shape.
      * @param iri - 完整 IRI
      * @returns 是否删除成功
      *
@@ -540,7 +850,7 @@ export class PodDatabase {
      * )
      * ```
      */
-    async deleteByIri(table, iri) {
+    async deleteByIri(resource, iri) {
         if (!iri || typeof iri !== 'string') {
             throw new Error('deleteByIri requires a valid IRI string');
         }
@@ -548,23 +858,37 @@ export class PodDatabase {
             throw new Error(`deleteByIri requires an absolute IRI, got: ${iri}`);
         }
         // 先检查实体是否存在
-        const existing = await this.findByIri(table, iri);
+        const existing = await this.findByIri(resource, iri);
         if (!existing) {
             return false;
         }
         // 使用 whereByIri 内部方法进行删除
         await this.session
-            .delete(table)
+            .delete(resource)
             .whereByIri(iri);
         return true;
     }
-    async deleteByLocator(table, locator) {
-        const iri = this.resolveLocatorSubject(table, locator, 'deleteByLocator');
-        return await this.deleteByIri(table, iri);
+    async deleteById(resource, id) {
+        const iri = await this.resolveIdSubjectForExactOperation(resource, id, 'deleteById');
+        if (!iri) {
+            return false;
+        }
+        return await this.deleteByIri(resource, iri);
     }
-    async deleteByResource(table, target) {
-        const iri = this.resolveResourceTargetIri(table, target, 'deleteByResource');
-        return await this.deleteByIri(table, iri);
+    /**
+     * @deprecated Use deleteById(resource, id), deleteByResource(resource, target), or deleteByIri(resource, iri).
+     * This locator-shaped exact delete will be removed in a future release.
+     */
+    async deleteByLocator(resource, locator) {
+        const iri = this.resolveLocatorSubject(resource, locator, 'deleteByLocator');
+        return await this.deleteByIri(resource, iri);
+    }
+    async deleteByResource(resource, target) {
+        if (typeof target === 'string' && this.needsShortIdSubjectLookup(resource, target)) {
+            return await this.deleteById(resource, target);
+        }
+        const iri = this.resolveResourceTargetIri(resource, target, 'deleteByResource');
+        return await this.deleteByIri(resource, iri);
     }
     // 事务支持
     async transaction(transaction) {
@@ -604,9 +928,9 @@ export class PodDatabase {
         return await this.dialect.disconnect();
     }
     /**
-     * 订阅表/资源的变化通知
+     * 订阅资源的变化通知
      *
-     * @param table - 要订阅的表（会订阅其容器或资源）
+     * @param resource - 要订阅的 resource（会订阅其容器或文档）
      * @param options - 订阅选项，支持按类型分开的回调
      * @returns 订阅句柄，可用于取消订阅
      *
@@ -633,7 +957,7 @@ export class PodDatabase {
      * subscription.unsubscribe();
      * ```
      */
-    async subscribe(table, options) {
+    async subscribe(resource, options) {
         // 懒初始化 NotificationsClient
         if (!this.notificationsClient) {
             const authenticatedFetch = this.dialect.getAuthenticatedFetch();
@@ -642,8 +966,8 @@ export class PodDatabase {
             };
             this.notificationsClient = new NotificationsClient(authenticatedFetch, config);
         }
-        // 获取表的资源 URL（容器或文件），支持 iri 覆盖
-        const topic = this.resolveTableTopic(table, options.iri);
+        // 获取 resource URL（容器或文件），支持 iri 覆盖
+        const topic = this.resolveResourceTopic(resource, options.iri);
         // 将 TableSubscribeOptions 转换为底层 SubscribeOptions
         const subscribeOptions = {
             channel: options.channel,
@@ -686,11 +1010,11 @@ export class PodDatabase {
         return this.notificationsClient.subscribe(topic, subscribeOptions);
     }
     /**
-     * 解析表对应的订阅主题 URL
-     * @param table 表定义
+     * 解析 resource 对应的订阅主题 URL
+     * @param resource Resource definition
      * @param iriOverride 可选的 IRI 覆盖（用于订阅其他 Pod 的资源）
      */
-    resolveTableTopic(table, iriOverride) {
+    resolveResourceTopic(resource, iriOverride) {
         // 如果提供了 iri 覆盖，直接使用
         if (iriOverride) {
             if (!iriOverride.startsWith('http://') && !iriOverride.startsWith('https://')) {
@@ -698,7 +1022,7 @@ export class PodDatabase {
             }
             return iriOverride;
         }
-        const base = table.config.base || '';
+        const base = resource.config.base || '';
         // 如果 base 已经是绝对 URL，直接使用
         if (base.startsWith('http://') || base.startsWith('https://')) {
             return base;
@@ -1063,13 +1387,13 @@ export class PodDatabase {
         const schemaEntries = (this.schema && typeof this.schema === 'object')
             ? Object.entries(this.schema)
             : [];
-        const tableMap = new Map();
+        const resourceMap = new Map();
         for (const [key, value] of schemaEntries) {
             if (isPodTable(value)) {
-                tableMap.set(key, value);
+                resourceMap.set(key, value);
             }
         }
-        const createHelper = (_tableName, table) => {
+        const createHelper = (_resourceName, resource) => {
             const createLazy = (executor) => {
                 let promise = null;
                 const run = () => {
@@ -1112,7 +1436,7 @@ export class PodDatabase {
             };
             const executeFindMany = async (options) => {
                 this.clearFederatedErrors();
-                let builder = this.session.select().from(table);
+                let builder = this.session.select().from(resource);
                 if (options?.where) {
                     builder = builder.where(options.where);
                 }
@@ -1130,7 +1454,7 @@ export class PodDatabase {
                 }
                 let rows = await builder;
                 if (options?.with && Object.keys(options.with).length > 0) {
-                    rows = await this.eagerLoadWith(rows, table, options.with, tableMap);
+                    rows = await this.eagerLoadWith(rows, resource, options.with, resourceMap);
                 }
                 const columns = options?.columns;
                 if (columns) {
@@ -1145,7 +1469,7 @@ export class PodDatabase {
                 }
                 let rows = [row];
                 if (options?.with && Object.keys(options.with).length > 0) {
-                    rows = await this.eagerLoadWith(rows, table, options.with, tableMap);
+                    rows = await this.eagerLoadWith(rows, resource, options.with, resourceMap);
                 }
                 const columns = options?.columns;
                 if (columns) {
@@ -1161,12 +1485,16 @@ export class PodDatabase {
                 const rows = await executeFindMany({ where: options?.where, columns: undefined, limit: undefined, offset: undefined });
                 return rows.length;
             });
-            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));
-            const createFindByResource = () => (target, options) => createLazy(async () => await applyExactOptions(await this.findByResource(table, target), options));
+            const createFindByLocator = () => (locator, options) => createLazy(async () => await applyExactOptions(await this.findByLocator(resource, locator), options));
+            const createFindById = () => (id, options) => createLazy(async () => await applyExactOptions(await this.findById(resource, id), options));
+            const createFindByIri = () => (iri, options) => createLazy(async () => await applyExactOptions(await this.findByIri(resource, iri), options));
+            const createFindByResource = () => (target, options) => createLazy(async () => await applyExactOptions(await this.findByResource(resource, target), options));
+            const find = (target, options) => createFindByResource()(target, options);
             return {
                 findMany,
                 findFirst,
+                find,
+                findById: createFindById(),
                 findByLocator: createFindByLocator(),
                 findByIri: createFindByIri(),
                 findByResource: createFindByResource(),
@@ -1179,9 +1507,9 @@ export class PodDatabase {
                 if (typeof prop !== 'string') {
                     return undefined;
                 }
-                const table = tableMap.get(prop);
-                if (table) {
-                    return createHelper(prop, table);
+                const resource = resourceMap.get(prop);
+                if (resource) {
+                    return createHelper(prop, resource);
                 }
                 return undefined;
             }
@@ -1496,4 +1824,5 @@ export class PodDatabase {
 }
 _a = entityKind;
 PodDatabase[_a] = 'PodDatabase';
+PodDatabase.findByLocatorDeprecationWarned = false;
 //# sourceMappingURL=pod-database.js.map