@undefineds.co/drizzle-solid 0.2.6

package/dist/core/notifications/types.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Solid Notifications Protocol 类型定义
+ * @see https://solid.github.io/notifications/protocol
+ */
+/**
+ * 通知事件类型（Activity Streams 2.0）
+ */
+export type NotificationType = 'Create' | 'Update' | 'Delete' | 'Add' | 'Remove';
+/**
+ * Activity Streams 2.0 Object
+ * 可以是简单的 URI 字符串，也可以是完整的对象（未来扩展）
+ * @see https://www.w3.org/TR/activitystreams-core/#object
+ */
+export type ActivityObject = string | {
+    /** 对象 URI */
+    id: string;
+    /** 对象类型 */
+    type?: string;
+    /** 新数据（未来扩展） */
+    new?: Record<string, unknown>;
+    /** 旧数据（未来扩展） */
+    old?: Record<string, unknown>;
+    /** 其他属性 */
+    [key: string]: unknown;
+};
+/**
+ * Activity Streams 2.0 Activity
+ * @see https://www.w3.org/TR/activitystreams-core/#activities
+ */
+export interface Activity {
+    /** Activity 唯一 ID */
+    id: string;
+    /** Activity 类型 */
+    type: NotificationType;
+    /** 变更的资源（URI 或对象） */
+    object: ActivityObject;
+    /** 目标容器（Add/Remove 时） */
+    target?: string;
+    /** 发布时间（ISO 8601） */
+    published: string;
+    /** 状态 token */
+    state?: string;
+}
+/**
+ * 通知事件（兼容旧接口）
+ * @deprecated 使用 Activity 代替
+ */
+export interface NotificationEvent {
+    /** 事件唯一 ID */
+    id: string;
+    /** 事件类型 */
+    type: NotificationType;
+    /** 变更的资源 URL */
+    object: string;
+    /** 事件发布时间（ISO 8601） */
+    published: string;
+    /** 变更后的资源状态（Turtle 格式，需要 state feature） */
+    state?: string;
+}
+/**
+ * 通道类型
+ */
+export type ChannelType = 'streaming-http' | 'websocket';
+/**
+ * 订阅特性
+ */
+export type SubscriptionFeature = 'state' | 'endAt' | 'rate';
+/**
+ * 订阅选项（旧接口，兼容）
+ */
+export interface SubscribeOptions {
+    /** 通道类型，默认 'streaming-http' (SSE) */
+    channel?: ChannelType;
+    /** 订阅特性 */
+    features?: SubscriptionFeature[];
+    /** 收到通知时的回调 */
+    onNotification: (event: NotificationEvent) => void;
+    /** 发生错误时的回调 */
+    onError?: (error: Error) => void;
+    /** 连接关闭时的回调 */
+    onClose?: () => void;
+    /**
+     * 是否启用自动重连（默认 true）
+     * 当连接断开时（如 xpod node_id 切换），自动重新订阅
+     */
+    autoReconnect?: boolean;
+    /**
+     * 最大重连次数（默认 5）
+     * 设为 0 或 Infinity 表示无限重连
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * 重连延迟基数（默认 1000ms）
+     * 实际延迟 = baseDelay * 2^attempt（指数退避）
+     */
+    reconnectDelayMs?: number;
+    /**
+     * 重连时的回调
+     */
+    onReconnect?: (attempt: number) => void;
+}
+/**
+ * 表订阅选项（新接口，按类型分开）
+ */
+export interface TableSubscribeOptions {
+    /**
+     * 覆盖订阅目标的 IRI（用于订阅其他 Pod 的资源）
+     *
+     * @example
+     * // 订阅自己的 profile（使用 table 的 base）
+     * db.subscribe(profileTable, { onUpdate: ... })
+     *
+     * // 订阅 Alice 的 profile
+     * db.subscribe(profileTable, {
+     *   iri: 'https://alice.pod/profile/card.ttl',
+     *   onUpdate: ...
+     * })
+     */
+    iri?: string;
+    /** 通道类型，默认 'streaming-http' (SSE) */
+    channel?: ChannelType;
+    /** 订阅特性 */
+    features?: SubscriptionFeature[];
+    /** 原始通知回调（服务端通知的原始形态） */
+    onNotification?: (event: NotificationEvent) => void;
+    /** 资源创建时的回调（服务端通知按类型分发） */
+    onCreate?: (activity: Activity) => void | Promise<void>;
+    /** 资源更新时的回调（服务端通知按类型分发） */
+    onUpdate?: (activity: Activity) => void | Promise<void>;
+    /** 资源删除时的回调（服务端通知按类型分发） */
+    onDelete?: (activity: Activity) => void | Promise<void>;
+    /** 添加到容器时的回调（服务端通知按类型分发） */
+    onAdd?: (activity: Activity) => void | Promise<void>;
+    /** 从容器移除时的回调（服务端通知按类型分发） */
+    onRemove?: (activity: Activity) => void | Promise<void>;
+    /** 发生错误时的回调 */
+    onError?: (error: Error) => void;
+    /** 连接关闭时的回调 */
+    onClose?: () => void;
+}
+/**
+ * 订阅句柄
+ */
+export interface Subscription {
+    /** 取消订阅 */
+    unsubscribe(): void;
+    /** 订阅是否活跃 */
+    readonly active: boolean;
+    /** 通道类型 */
+    readonly channel: ChannelType;
+    /** 订阅的主题（资源 URL） */
+    readonly topic: string;
+}
+/**
+ * Notifications 服务发现响应
+ */
+export interface NotificationServiceDescription {
+    /** 订阅端点 URL */
+    subscriptionEndpoint: string;
+    /** 支持的通道类型 */
+    channelTypes: string[];
+    /** 支持的特性 */
+    features?: string[];
+}
+/**
+ * 订阅请求体
+ */
+export interface SubscriptionRequest {
+    '@context': string[];
+    type: string;
+    topic: string;
+    features?: string[];
+}
+/**
+ * 订阅响应体
+ */
+export interface SubscriptionResponse {
+    '@context': string[];
+    id: string;
+    type: string;
+    topic: string;
+    receiveFrom: string;
+    features?: string[];
+}
+/**
+ * Channel 接口（内部使用）
+ */
+export interface NotificationChannel {
+    /** 连接到通知服务 */
+    connect(): Promise<void>;
+    /** 断开连接 */
+    disconnect(): void;
+    /** 是否已连接 */
+    readonly connected: boolean;
+}
+/**
+ * Channel 配置（内部使用）
+ */
+export interface ChannelConfig {
+    /** 接收通知的 URL（WebSocket URL 或 SSE URL） */
+    receiveFrom: string;
+    /** 收到通知时的回调 */
+    onNotification: (event: NotificationEvent) => void;
+    /** 发生错误时的回调 */
+    onError?: (error: Error) => void;
+    /** 连接关闭时的回调 */
+    onClose?: () => void;
+    /** 认证 fetch 函数 */
+    fetch?: typeof fetch;
+}
+/**
+ * 单体订阅选项（用于 subscribeByIri）
+ *
+ * 与容器订阅不同，单体订阅没有 onCreate 回调（实体已存在）
+ */
+export interface EntitySubscribeOptions<TData = unknown> {
+    /** 通道类型，默认 'streaming-http' (SSE) */
+    channel?: ChannelType;
+    /** 订阅特性 */
+    features?: SubscriptionFeature[];
+    /** 数据更新时的回调（收到通知后自动重新获取数据） */
+    onUpdate: (data: TData) => void | Promise<void>;
+    /** 实体删除时的回调 */
+    onDelete?: () => void | Promise<void>;
+    /** 发生错误时的回调（如权限撤销、网络错误） */
+    onError?: (error: Error) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/notifications/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/notifications/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,MAAM,gBAAgB,GACxB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,KAAK,GACL,QAAQ,CAAC;AAEb;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG;IACpC,aAAa;IACb,EAAE,EAAE,MAAM,CAAC;IACX,WAAW;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,gBAAgB;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,WAAW;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,qBAAqB;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB;IAClB,IAAI,EAAE,gBAAgB,CAAC;IACvB,qBAAqB;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,cAAc;IACd,EAAE,EAAE,MAAM,CAAC;IACX,WAAW;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,gBAAgB;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAEzD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qCAAqC;IACrC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,WAAW;IACX,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,eAAe;IACf,cAAc,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACnD,eAAe;IACf,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,eAAe;IACf,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,WAAW;IACX,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,yBAAyB;IACzB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACpD,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,4BAA4B;IAC5B,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,eAAe;IACf,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,eAAe;IACf,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW;IACX,WAAW,IAAI,IAAI,CAAC;IACpB,aAAa;IACb,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,WAAW;IACX,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,oBAAoB;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,eAAe;IACf,oBAAoB,EAAE,MAAM,CAAC;IAC7B,cAAc;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY;IACZ,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,cAAc;IACd,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,WAAW;IACX,UAAU,IAAI,IAAI,CAAC;IACnB,YAAY;IACZ,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe;IACf,cAAc,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACnD,eAAe;IACf,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,eAAe;IACf,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,kBAAkB;IAClB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,KAAK,GAAG,OAAO;IACrD,qCAAqC;IACrC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,WAAW;IACX,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,8BAA8B;IAC9B,QAAQ,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,2BAA2B;IAC3B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC"}

package/dist/core/notifications/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Solid Notifications Protocol 类型定义
+ * @see https://solid.github.io/notifications/protocol
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/core/notifications/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/notifications/types.ts"],"names":[],"mappings":";AAAA;;;GAGG"}

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

@@ -0,0 +1,383 @@
+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 { type TableSubscribeOptions, type EntitySubscribeOptions, type Subscription } from './notifications';
+import { type FederatedError } from './federated';
+import type { DataDiscovery } from './discovery';
+/**
+ * 初始化表选项
+ */
+export interface InitOptions {
+    /** 是否生成 Shape 定义 */
+    generateShape?: boolean;
+    /** 是否保存 Shape 到 Pod（需要 generateShape 为 true） */
+    saveShape?: boolean;
+    /** Shape 保存位置（容器路径或完整 URL），默认为 Pod 根目录下的 /shapes/ */
+    shapeLocation?: string;
+}
+export declare class PodDatabase<TSchema extends Record<string, unknown> = Record<string, never>> {
+    dialect: PodDialect;
+    session: PodAsyncSession;
+    schema?: TSchema | undefined;
+    static readonly [entityKind] = "PodDatabase";
+    private notificationsClient;
+    private federatedExecutor;
+    /** 最近一次联邦查询的错误（如果有） */
+    private lastFederatedErrors;
+    constructor(dialect: PodDialect, session: PodAsyncSession, schema?: TSchema | undefined);
+    /**
+     * 获取最近一次联邦查询的错误
+     * 在调用 findMany 等方法后可以检查此值
+     */
+    getLastFederatedErrors(): FederatedError[];
+    /**
+     * 清除联邦查询错误
+     */
+    clearFederatedErrors(): void;
+    /**
+     * 获取或创建 FederatedQueryExecutor
+     */
+    private getFederatedExecutor;
+    /**
+     * Create a table from a schema with hooks
+     *
+     * This is the recommended way to create tables when you need hooks that
+     * can access the database instance (e.g., for cross-table operations).
+     *
+     * @param schema - The schema definition (created via solidSchema())
+     * @param options - Table options including base path and hooks
+     * @returns A PodTable instance with hooks bound to this database
+     *
+     * @example
+     * ```typescript
+     * const userSchema = solidSchema('users', {
+     *   id: id(),
+     *   name: text('name').predicate(SCHEMA.name),
+     *   email: text('email').predicate(SCHEMA.email),
+     * }, {
+     *   type: SCHEMA.Person,
+     * });
+     *
+     * const userTable = db.createTable(userSchema, {
+     *   base: '/data/users/',
+     *   hooks: {
+     *     afterInsert: async (ctx, record) => {
+     *       // ctx.db is available - can query/insert other tables
+     *       await ctx.db.insert(auditTable).values({
+     *         action: 'user_created',
+     *         userId: record['@id'],
+     *       });
+     *     },
+     *     afterUpdate: async (ctx, record, changes) => {
+     *       if ('email' in changes) {
+     *         // Send verification email via another service
+     *         await ctx.db.insert(notificationTable).values({
+     *           type: 'email_changed',
+     *           userId: record['@id'],
+     *         });
+     *       }
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    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>;
+    findFirst<TTable extends PodTable<any>>(table: TTable, where?: Record<string, unknown>): Promise<InferTableData<TTable> | null>;
+    /**
+     * 通过完整 IRI 查询单个实体
+     *
+     * @param table - 表定义（用于解析 schema）
+     * @param iri - 完整 IRI，本地或远程
+     * @returns 实体数据，如果不存在则返回 null
+     *
+     * @example
+     * ```typescript
+     * // 本地 Agent
+     * db.findByIri(agentTable, 'https://my.pod/agents/translator')
+     *
+     * // 远程 Profile
+     * db.findByIri(solidProfileTable, 'https://alice.pod/profile/card#me')
+     *
+     * // 业务层不区分本地远程
+     * db.findByIri(agentTable, contact.entityUri)
+     * ```
+     */
+    findByIri<TTable extends PodTable<any>>(table: TTable, iri: string): Promise<InferTableData<TTable> | null>;
+    /**
+     * 解析 IRI 为文档 URL 和 fragment
+     */
+    private parseIri;
+    /**
+     * 通过完整 IRI 订阅单个实体的变更
+     *
+     * @param table - 表定义
+     * @param iri - 完整 IRI，本地或远程
+     * @param options - 订阅选项
+     * @returns 取消订阅函数
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = await db.subscribeByIri(
+     *   solidProfileTable,
+     *   'https://alice.pod/profile/card#me',
+     *   {
+     *     onUpdate: (data) => {
+     *       console.log('Profile updated:', data.name)
+     *     },
+     *     onDelete: () => {
+     *       console.log('Profile deleted')
+     *     },
+     *     onError: (error) => {
+     *       console.log('Subscription error:', error)
+     *     }
+     *   }
+     * )
+     *
+     * // 离开时取消订阅
+     * unsubscribe()
+     * ```
+     */
+    subscribeByIri<TTable extends PodTable<any>>(table: TTable, iri: string, options: EntitySubscribeOptions<InferTableData<TTable>>): Promise<() => void>;
+    /**
+     * 通过完整 IRI 更新单个实体
+     *
+     * @param table - 表定义
+     * @param iri - 完整 IRI
+     * @param data - 要更新的数据
+     * @returns 更新后的实体数据
+     *
+     * @example
+     * ```typescript
+     * const updated = await db.updateByIri(
+     *   agentTable,
+     *   'https://my.pod/agents/translator#agent',
+     *   { name: 'New Name', description: 'Updated description' }
+     * )
+     * ```
+     */
+    updateByIri<TTable extends PodTable<any>>(table: TTable, iri: string, data: Partial<Omit<InferTableData<TTable>, '@id' | 'id'>>): Promise<InferTableData<TTable> | null>;
+    /**
+     * 通过完整 IRI 删除单个实体
+     *
+     * @param table - 表定义
+     * @param iri - 完整 IRI
+     * @returns 是否删除成功
+     *
+     * @example
+     * ```typescript
+     * const deleted = await db.deleteByIri(
+     *   agentTable,
+     *   'https://my.pod/agents/translator#agent'
+     * )
+     * ```
+     */
+    deleteByIri<TTable extends PodTable<any>>(table: TTable, iri: string): Promise<boolean>;
+    transaction<T>(transaction: (tx: PodDatabase<TSchema>) => Promise<T>): Promise<T>;
+    getDialect(): PodDialect;
+    getSession(): PodAsyncSession;
+    getSchema(): TSchema | undefined;
+    /**
+     * 数据发现入口（TypeIndex + SAI 组合策略）
+     */
+    get discovery(): DataDiscovery;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    /**
+     * 订阅表/资源的变化通知
+     *
+     * @param table - 要订阅的表（会订阅其容器或资源）
+     * @param options - 订阅选项，支持按类型分开的回调
+     * @returns 订阅句柄，可用于取消订阅
+     *
+     * @example
+     * ```typescript
+     * const subscription = await db.subscribe(posts, {
+     *   onCreate: async (activity) => {
+     *     console.log('Created:', activity.object);
+     *     const latest = await db.select().from(posts);
+     *   },
+     *   onUpdate: async (activity) => {
+     *     console.log('Updated:', activity.object);
+     *     const latest = await db.select().from(posts);
+     *   },
+     *   onDelete: (activity) => {
+     *     console.log('Deleted:', activity.object);
+     *   },
+     *   onError: (error) => {
+     *     console.error('Subscription error:', error);
+     *   }
+     * });
+     *
+     * // 取消订阅
+     * subscription.unsubscribe();
+     * ```
+     */
+    subscribe<TTable extends PodTable<any>>(table: TTable, options: TableSubscribeOptions): Promise<Subscription>;
+    /**
+     * 解析表对应的订阅主题 URL
+     * @param table 表定义
+     * @param iriOverride 可选的 IRI 覆盖（用于订阅其他 Pod 的资源）
+     */
+    private resolveTableTopic;
+    getConfig(): {
+        podUrl: string;
+        webId: string;
+        connected: boolean;
+    };
+    /**
+     * 通过 RDF 类型自动发现并生成表定义
+     *
+     * 流程：
+     * 1. 通过 TypeIndex/Interop 发现数据位置
+     * 2. 如果有 ShapeTree/Shape，加载并解析
+     * 3. 从 Shape 生成 PodTable 定义
+     *
+     * @param rdfClass RDF 类型 URI (如 'http://schema.org/Person')
+     * @returns 生成的 PodTable，如果未发现则返回 null
+     *
+     * @example
+     * ```typescript
+     * // 自动发现 Person 类型的表
+     * const persons = await db.discoverTable('http://schema.org/Person');
+     * if (persons) {
+     *   const data = await db.select().from(persons);
+     * }
+     * ```
+     */
+    discoverTable(rdfClass: string): Promise<PodTable | null>;
+    /**
+     * 发现多个类型的表
+     */
+    discoverTables(rdfClasses: string[]): Promise<PodTable[]>;
+    /**
+     * 发现某类型数据的所有位置
+     * @param rdfClass RDF 类型 URI
+     * @param options 可选的过滤选项
+     * @returns 数据位置列表
+     *
+     * @example
+     * ```typescript
+     * // 发现所有 Person 类型的数据位置
+     * const locations = await db.discover('https://schema.org/Person');
+     *
+     * // 按 appId 过滤
+     * const acmeLocations = await db.discover('https://schema.org/Person', {
+     *   appId: 'https://acme.com/app#id'
+     * });
+     * ```
+     */
+    discover(rdfClass: string, options?: import('./discovery').DiscoverOptions): Promise<import('./discovery').DataLocation[]>;
+    /**
+     * 获取所有数据注册信息
+     * @returns 所有注册的数据信息列表
+     *
+     * @example
+     * ```typescript
+     * const allRegistrations = await db.discoverAll();
+     * for (const reg of allRegistrations) {
+     *   console.log(`${reg.rdfClass} at ${reg.container}`);
+     *   console.log(`  Shape: ${reg.shape}`);
+     *   console.log(`  Registered by: ${reg.registeredBy}`);
+     * }
+     * ```
+     */
+    discoverAll(): Promise<import('./discovery').DataRegistrationInfo[]>;
+    /**
+     * 按应用 ID 发现数据位置
+     * @param appId 应用标识符
+     * @returns 该应用注册的数据位置列表
+     *
+     * @example
+     * ```typescript
+     * const acmeData = await db.discoverByApp('https://acme.com/app#id');
+     * ```
+     */
+    discoverByApp(appId: string): Promise<import('./discovery').DataLocation[]>;
+    /**
+     * 从 DataLocation 创建 PodTable
+     * 如果 location 有 shape，会加载 Shape 并生成完整的表定义
+     *
+     * @param location 数据位置信息
+     * @param options 转换选项，可指定使用哪个 Shape
+     * @returns PodTable 实例
+     *
+     * @example
+     * ```typescript
+     * // 使用第一个可用的 Shape
+     * const table = await db.locationToTable(location);
+     *
+     * // 指定使用某个 app 注册的 Shape
+     * const table = await db.locationToTable(location, {
+     *   appId: 'https://acme.com/app#id'
+     * });
+     *
+     * // 直接传入 ShapeInfo 对象
+     * const table = await db.locationToTable(location, {
+     *   shape: location.shapes[0]
+     * });
+     *
+     * // 或者传入 Shape URL
+     * const table = await db.locationToTable(location, {
+     *   shape: 'https://shapes.example/Person.shacl'
+     * });
+     * ```
+     */
+    locationToTable(location: import('./discovery').DataLocation, options?: import('./discovery').LocationToTableOptions): Promise<PodTable>;
+    /**
+     * 从容器 URL 提取表名
+     */
+    private extractContainerName;
+    /**
+     * 发现并转换为表 - 支持按 appId 过滤
+     *
+     * @param rdfClass RDF 类型 URI
+     * @param options 发现选项
+     * @param tableOptions 转表选项（指定使用哪个 Shape）
+     *
+     * @example
+     * ```typescript
+     * // 发现所有 Person 表
+     * const allPersonTables = await db.discoverTablesFor('schema:Person');
+     *
+     * // 只要 Acme app 的 Person 表，并使用 Acme 的 Shape
+     * const acmePersonTable = await db.discoverTablesFor('schema:Person',
+     *   { appId: 'https://acme.com/app#id' },
+     *   { appId: 'https://acme.com/app#id' }
+     * );
+     * ```
+     */
+    discoverTablesFor(rdfClass: string, options?: import('./discovery').DiscoverOptions, tableOptions?: import('./discovery').LocationToTableOptions): Promise<PodTable[]>;
+    /**
+     * 从 predicate URI 提取列名
+     */
+    private predicateToColumnName;
+    /**
+     * 从 RDF 类型 URI 提取类名
+     */
+    private extractClassName;
+    addSource(source: string): void;
+    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>;
+    private queryProxy?;
+    get query(): Record<string, any>;
+    private buildQueryProxy;
+    private eagerLoadWith;
+    private dedupeBySubject;
+    private resolveIdFromRow;
+    private resolveParentKey;
+    private resolveIriFromRow;
+    private normalizeReferenceValue;
+    private normalizeLiteralValue;
+    private collectInverseReferenceValues;
+    private groupRowsByIri;
+    private extractFragment;
+}
+//# sourceMappingURL=pod-database.d.ts.map

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

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