@undefineds.co/xpod 0.4.14 → 0.4.16

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

@@ -1,548 +0,0 @@
-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 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';
-/**
- * 初始化表选项
- */
-export interface InitOptions {
-    /** 是否生成 Shape 定义 */
-    generateShape?: boolean;
-    /** 是否保存 Shape 到 Pod（需要 generateShape 为 true） */
-    saveShape?: boolean;
-    /** Shape 保存位置（容器路径或完整 URL），默认为 Pod 根目录下的 /shapes/ */
-    shapeLocation?: string;
-}
-type GenericPodTable = PodTable<any>;
-type GenericPodResource = GenericPodTable;
-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;
-    }>;
-};
-export type ResourceFileInput = {
-    path?: string;
-    url?: string;
-    content?: BodyInit | null;
-    contentType?: string;
-    relationField?: string;
-};
-export type ResourceWithDocumentInput = {
-    row: Record<string, unknown>;
-    document?: ResourceFileInput;
-    source?: ResourceFileInput;
-    files?: ResourceFileInput[];
-};
-export type PlannedResourceFileWrite = {
-    relationField: string;
-    url: string;
-    contentType?: string;
-};
-export type ResourceWithDocumentPlan = {
-    ok: true;
-    resourceId: string;
-    resourceIri: string;
-    row: Record<string, unknown>;
-    rdfMutations: Array<{
-        type: 'upsert';
-        subject: string;
-        fields: string[];
-    }>;
-    fileWrites: PlannedResourceFileWrite[];
-    warnings: string[];
-    errors: string[];
-};
-export type MoveDocumentInput = {
-    id: string;
-    relationField?: string;
-    fromPath?: string;
-    fromUrl?: string;
-    toPath?: string;
-    toUrl?: string;
-    content?: BodyInit | null;
-    contentType?: string;
-};
-export type DeleteResourceWithDocumentInput = {
-    id: string;
-    relationField?: string;
-    path?: string;
-    url?: string;
-};
-type QueryResourceHelper<TResource extends GenericPodResource = GenericPodResource> = {
-    findMany<T = InferTableData<TResource>>(options?: QueryFindManyOptions): Promise<T[]>;
-    findFirst<T = InferTableData<TResource>>(options?: QueryFindManyOptions): Promise<T | null>;
-    find<T = InferTableData<TResource>>(target: string | EntityLocator, options?: QueryExactOptions): Promise<T | null>;
-    findById<T = InferTableData<TResource>>(id: string, options?: QueryExactOptions): Promise<T | null>;
-    findByResource<T = InferTableData<TResource>>(target: string | EntityLocator, options?: QueryExactOptions): Promise<T | null>;
-    findByLocator<T = InferTableData<TResource>>(locator: EntityLocator, options?: QueryExactOptions): Promise<T | null>;
-    findByIri<T = InferTableData<TResource>>(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 ? QueryResourceHelper<TSchema[K]> : never;
-};
-export declare class PodDatabase<TSchema extends Record<string, unknown> = Record<string, never>> {
-    dialect: PodDialect;
-    session: PodAsyncSession;
-    schema?: TSchema | undefined;
-    static readonly [entityKind] = "PodDatabase";
-    private static findByLocatorDeprecationWarned;
-    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>>(schema: SolidSchema<TColumns>, options: InstantiateTableOptions): PodTable<TColumns>;
-    select<TTable extends GenericPodTable = GenericPodTable>(fields?: SelectFieldMap): SelectQueryBuilder<TTable>;
-    insert<TTable extends GenericPodTable>(table: TTable): InsertQueryBuilder<TTable>;
-    update<TTable extends GenericPodTable>(table: TTable): UpdateQueryBuilder<TTable>;
-    delete<TTable extends GenericPodTable>(table: TTable): DeleteQueryBuilder<TTable>;
-    private resolvePodFileUrl;
-    private getResourceFileInputs;
-    private validateNoDuplicatePathComposition;
-    dryRunResourceWithDocument<TTable extends GenericPodTable>(resource: TTable, input: ResourceWithDocumentInput): Promise<ResourceWithDocumentPlan>;
-    upsertResourceWithDocument<TTable extends GenericPodTable>(resource: TTable, input: ResourceWithDocumentInput): Promise<ResourceWithDocumentPlan>;
-    moveDocumentAndRelink<TTable extends GenericPodTable>(resource: TTable, input: MoveDocumentInput): Promise<{
-        fromUrl?: string;
-        toUrl: string;
-        resource: unknown | null;
-    }>;
-    deleteResourceWithDocument<TTable extends GenericPodTable>(resource: TTable, input: DeleteResourceWithDocumentInput): Promise<{
-        deleted: boolean;
-        fileUrl?: string;
-    }>;
-    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 GenericPodTable>(table: TTable, where?: PublicWhereObject): Promise<InferTableData<TTable> | null>;
-    private getLocatorTemplate;
-    private getRequiredLocatorKeys;
-    private resolveResourceTargetIri;
-    private resolveLocatorSubject;
-    private resolveIdSubject;
-    private warnFindByLocatorDeprecation;
-    private getIriAlternative;
-    resolveLocatorIri<TTable extends GenericPodTable>(resource: TTable, locator: EntityLocator): string;
-    resolveLocatorId<TTable extends GenericPodTable>(resource: TTable, locator: EntityLocator): string;
-    resolveResourceIri<TTable extends GenericPodTable>(resource: TTable, target: string | EntityLocator): string;
-    resolveResourceId<TTable extends GenericPodTable>(resource: TTable, target: string | EntityLocator): string;
-    resolveRelationIri<TTable extends GenericPodTable>(resource: TTable, target: string | EntityLocator): string;
-    resolveRowIri<TTable extends GenericPodTable>(resource: TTable, row: EntityLocator): string;
-    resolveRowId<TTable extends GenericPodTable>(resource: TTable, row: EntityLocator): string;
-    private resolveBaseRelativeResourceId;
-    private needsShortIdSubjectLookup;
-    private buildShortIdSubjectSuffix;
-    private resolveShortIdLookupSource;
-    private extractSubjectFromLookupRow;
-    private subjectMatchesShortId;
-    private getIndexedSubject;
-    private lookupSubjectIriByShortId;
-    private resolveIdSubjectForExactOperation;
-    findById<TTable extends GenericPodTable>(resource: TTable, id: string): Promise<InferTableData<TTable> | null>;
-    findById<TRow = unknown>(resource: GenericPodResource, id: string): Promise<TRow | null>;
-    /**
-     * @deprecated Use findById(resource, id), findByResource(resource, target), or findByIri(resource, iri).
-     * This locator-shaped exact lookup will be removed in a future release.
-     */
-    findByLocator<TTable extends GenericPodTable>(resource: TTable, locator: EntityLocator): Promise<InferTableData<TTable> | null>;
-    findByLocator<TRow = unknown>(resource: GenericPodResource, locator: EntityLocator): Promise<TRow | null>;
-    findByResource<TTable extends GenericPodTable>(resource: TTable, target: string | EntityLocator): Promise<InferTableData<TTable> | null>;
-    findByResource<TRow = unknown>(resource: GenericPodResource, target: string | EntityLocator): Promise<TRow | null>;
-    /**
-     * 通过完整 IRI 查询单个实体
-     *
-     * @param resource - Resource definition used to decode schema and subject shape.
-     * @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 GenericPodTable>(resource: TTable, iri: string): Promise<InferTableData<TTable> | null>;
-    findByIri<TRow = unknown>(resource: GenericPodResource, iri: string): Promise<TRow | null>;
-    private getColumnPredicate;
-    private findByIriViaExactResource;
-    private readPredicateObjectRowsFromDocument;
-    private convertRdfTermToValue;
-    private isMissingExactResourceError;
-    private mapPredicateObjectRows;
-    private extractIdFromIri;
-    /**
-     * 解析 IRI 为文档 URL 和 fragment
-     */
-    private parseIri;
-    /**
-     * 通过完整 IRI 订阅单个实体的变更
-     *
-     * @param resource - Resource definition used to decode schema and subject shape.
-     * @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 GenericPodTable>(resource: TTable, iri: string, options: EntitySubscribeOptions<InferTableData<TTable>>): Promise<() => void>;
-    /**
-     * 通过完整 IRI 更新单个实体
-     *
-     * @param resource - Resource definition used to decode schema and subject shape.
-     * @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 GenericPodTable>(resource: TTable, iri: string, data: Partial<Omit<InferTableData<TTable>, '@id' | 'id'>>): Promise<InferTableData<TTable> | null>;
-    updateByIri<TRow = unknown>(resource: GenericPodResource, iri: string, data: Record<string, unknown>): Promise<TRow | null>;
-    updateById<TTable extends GenericPodTable>(resource: TTable, id: string, data: Partial<Omit<InferTableData<TTable>, '@id' | 'id'>>): Promise<InferTableData<TTable> | null>;
-    updateById<TRow = unknown>(resource: GenericPodResource, id: string, data: Record<string, unknown>): Promise<TRow | null>;
-    /**
-     * @deprecated Use updateById(resource, id, data), updateByResource(resource, target, data), or updateByIri(resource, iri, data).
-     * This locator-shaped exact update will be removed in a future release.
-     */
-    updateByLocator<TTable extends GenericPodTable>(resource: TTable, locator: EntityLocator, data: Partial<Omit<InferTableData<TTable>, '@id' | 'id'>>): Promise<InferTableData<TTable> | null>;
-    updateByLocator<TRow = unknown>(resource: GenericPodResource, locator: EntityLocator, data: Record<string, unknown>): Promise<TRow | null>;
-    updateByResource<TTable extends GenericPodTable>(resource: TTable, target: string | EntityLocator, data: Partial<Omit<InferTableData<TTable>, '@id' | 'id'>>): Promise<InferTableData<TTable> | null>;
-    updateByResource<TRow = unknown>(resource: GenericPodResource, target: string | EntityLocator, data: Record<string, unknown>): Promise<TRow | null>;
-    /**
-     * 通过完整 IRI 删除单个实体
-     *
-     * @param resource - Resource definition used to decode schema and subject shape.
-     * @param iri - 完整 IRI
-     * @returns 是否删除成功
-     *
-     * @example
-     * ```typescript
-     * const deleted = await db.deleteByIri(
-     *   agentTable,
-     *   'https://my.pod/agents/translator#agent'
-     * )
-     * ```
-     */
-    deleteByIri<TTable extends GenericPodTable>(resource: TTable, iri: string): Promise<boolean>;
-    deleteById<TTable extends GenericPodTable>(resource: TTable, id: string): Promise<boolean>;
-    /**
-     * @deprecated Use deleteById(resource, id), deleteByResource(resource, target), or deleteByIri(resource, iri).
-     * This locator-shaped exact delete will be removed in a future release.
-     */
-    deleteByLocator<TTable extends GenericPodTable>(resource: TTable, locator: EntityLocator): Promise<boolean>;
-    deleteByResource<TTable extends GenericPodTable>(resource: TTable, target: string | EntityLocator): 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 resource - 要订阅的 resource（会订阅其容器或文档）
-     * @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 GenericPodTable>(resource: TTable, options: TableSubscribeOptions): Promise<Subscription>;
-    /**
-     * 解析 resource 对应的订阅主题 URL
-     * @param resource Resource definition
-     * @param iriOverride 可选的 IRI 覆盖（用于订阅其他 Pod 的资源）
-     */
-    private resolveResourceTopic;
-    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<GenericPodTable | null>;
-    /**
-     * 发现多个类型的表
-     */
-    discoverTables(rdfClasses: string[]): Promise<GenericPodTable[]>;
-    /**
-     * 发现某类型数据的所有位置
-     * @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<GenericPodTable>;
-    /**
-     * 从容器 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<GenericPodTable[]>;
-    /**
-     * 从 RDF 类型 URI 提取类名
-     */
-    private extractClassName;
-    addSource(source: string): void;
-    removeSource(source: string): void;
-    getSources(): string[];
-    addSourcesFromTypeIndex(): Promise<void>;
-    init<TTable extends GenericPodTable>(tables: TTable | TTable[], options?: InitOptions): Promise<void>;
-    init<TTable extends GenericPodTable>(...tables: Array<TTable | TTable[]>): Promise<void>;
-    private queryProxy?;
-    get query(): QueryProxy<TSchema>;
-    private buildQueryProxy;
-    private eagerLoadWith;
-    private dedupeBySubject;
-    private resolveIdFromRow;
-    private resolveParentKey;
-    private resolveIriFromRow;
-    private collectLinkLookupKeys;
-    private normalizeLinkValue;
-    private normalizeLiteralValue;
-    private collectInverseLinkValues;
-    private groupRowsByIri;
-    private extractFragment;
-}
-export {};
-//# sourceMappingURL=pod-database.d.ts.map