@decohere/data-typeorm 0.0.1-dev.116

package/types/src/data-source.factory.d.ts

@@ -0,0 +1,17 @@
+import type { ConnectionInfo } from "@decohere/data";
+import type { Constructable } from "@decohere/core/reflection";
+import { DataSource, type Logger } from "typeorm";
+export type ConnectionOptions = ConnectionInfo & {
+    entities: Constructable[];
+    applicationName?: string;
+};
+/**
+ * A DataSource the container can close: TypeORM's has `destroy()` but no `Symbol.asyncDispose`,
+ * so disposing the app's container used to leave its connections open (#541).
+ */
+export declare class ManagedDataSource extends DataSource {
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export declare class DataSourceFactory {
+    static create(options: ConnectionOptions, logger: Logger): DataSource;
+}

package/types/src/database-options.d.ts

@@ -0,0 +1,9 @@
+import type { Constructable } from "@decohere/core/reflection";
+import type { DataSource } from "typeorm";
+export type ModuleConfig = {
+    /** The unique identifier for the data source. Required when multiple data sources are configured. */
+    name?: string | symbol;
+    repositories?: Constructable[];
+    entities: Constructable[];
+    seed?: (dataSource: DataSource) => Promise<void>;
+};

package/types/src/dialect-map.d.ts

@@ -0,0 +1,8 @@
+export declare const ProviderMap: {
+    postgres: "postgres";
+    mssql: "mssql";
+};
+export declare const DialectMap: {
+    postgresql: "postgres";
+    tsql: "mssql";
+};

package/types/src/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./bootstrap.js";
+export * from "./inject-data-source.js";
+export * from "./sql-pretty.transport.js";
+export * from "./type-orm.provider.js";
+export * from "./type-orm.repository.js";
+export * from "./typeorm.extensions.js";
+export * from "./unit-of-work.js";

package/types/src/inject-data-source.d.ts

@@ -0,0 +1,14 @@
+/** Default TypeORM DataSource when `withTypeOrm` is used without `name`. */
+export declare const TypeOrmDataSourceToken: unique symbol;
+/**
+ * Container key for a TypeORM DataSource. Distinct from the unit-of-work key
+ * (datasource name / {@link DEFAULT_DATA_SOURCE}) so request-scoped UoW and
+ * process-lifetime DataSource can coexist.
+ */
+export declare function typeOrmDataSourceToken(name?: string | symbol): symbol;
+/**
+ * Inject the TypeORM DataSource for process-lifetime (singleton) work.
+ * Pass the same `name` as `withTypeOrm({ name })`. Request-scoped persistence
+ * should keep using `injectUnitOfWork`.
+ */
+export declare function injectDataSource(name?: string | symbol): (target: object, _propertyKey: string | symbol | undefined, idx: number) => void;

package/types/src/scripts/user.d.ts

@@ -0,0 +1,56 @@
+export declare function assertSafeSqlIdent(value: string, label: string): string;
+/** Double-quote a validated identifier for use in DDL. */
+export declare function quoteIdent(value: string, label?: string): string;
+/**
+ * Single-quote a string literal for DDL that cannot take bind parameters
+ * (e.g. CREATE USER … PASSWORD — Postgres rejects PASSWORD $1).
+ */
+export declare function quoteLiteral(value: string): string;
+export type SqlQuery = {
+    text: string;
+    values: unknown[];
+};
+/** Existence check — username bound as $1 (never concatenated). */
+export declare function roleExistsQuery(username: string): SqlQuery;
+/**
+ * CREATE USER with password as an escaped SQL literal.
+ * Username is validated + quoted as an identifier (cannot be parameterized in DDL).
+ * Password cannot use bind params in CREATE USER … PASSWORD (Postgres syntax error).
+ *
+ * `password` omitted (undefined) creates a role with no password, for a local dev server that
+ * trusts every connection. An empty string is still an error: that is a typo, not a choice.
+ * Callers decide when no password is allowed (see PostgresServerManager).
+ */
+export declare function createUserQuery(username: string, password?: string): SqlQuery;
+/** CONNECT only — production runtime app role. */
+export declare function grantConnectQuery(username: string, database: string): SqlQuery;
+export declare function grantSchemaUsageQuery(username: string, schema?: string): SqlQuery;
+/** Needed for TypeORM synchronize (dev only). */
+export declare function grantSchemaCreateQuery(username: string, schema?: string): SqlQuery;
+/** The schema, owned by `owner`. Unchanged when it already exists. */
+export declare function createSchemaQuery(schema: string, owner: string): SqlQuery;
+/**
+ * Whether a role already holds a privilege. Postgres checks that the grantor may grant even when
+ * the grant would change nothing, so bootstrap asks first and grants only what is missing.
+ */
+export declare function hasDatabasePrivilegeQuery(username: string, database: string, privilege: string): SqlQuery;
+export declare function hasSchemaPrivilegeQuery(username: string, schema: string, privilege: string): SqlQuery;
+/** Whether `member` already has the privileges of `role` (inherited, or as a superuser). */
+export declare function hasRolePrivilegesQuery(member: string, role: string): SqlQuery;
+export declare function databaseOwnerQuery(database: string): SqlQuery;
+export declare function grantSchemaPrivilegesQuery(username: string, schema?: string): SqlQuery;
+export declare function alterDatabaseOwnerQuery(database: string, username: string): SqlQuery;
+/**
+ * Postgres requires the session user to be a member of the target role to
+ * `ALTER DATABASE … OWNER TO` / `ALTER DEFAULT PRIVILEGES FOR ROLE`.
+ */
+export declare function grantRoleMembershipQuery(member: string, role: string): SqlQuery;
+export declare function revokeRoleMembershipQuery(member: string, role: string): SqlQuery;
+/**
+ * Future tables/sequences created by the migration role are usable by the app role (DML only).
+ */
+export declare function defaultPrivilegesForAppQueries(migrateUsername: string, appUsername: string, schema?: string): SqlQuery[];
+export declare const userScripts: {
+    createOwnerUser: (username: string, password: string, database: string) => SqlQuery;
+    userExists: (username: string) => SqlQuery;
+};

package/types/src/server-manager.d.ts

@@ -0,0 +1,39 @@
+import { type ConnectionInfo } from "@decohere/data";
+export type ProvisionRolesOptions = {
+    database: string;
+    appUsername: string;
+    /** Omit only when the server is declared `auth: trust`. */
+    appPassword?: string;
+    migrateUsername?: string;
+    migratePassword?: string;
+    /** When true (TypeORM synchronize), grant CREATE on the schema to the app role (dev only). */
+    allowAppDdl: boolean;
+    /** The schema the app role works in, created when missing. Default `public`. */
+    schema?: string;
+};
+export declare class PostgresServerManager {
+    private readonly applicationName;
+    private readonly config;
+    private pool;
+    private client;
+    constructor(applicationName: string, config: ConnectionInfo);
+    /** `auth: trust`: the server lets every connection in, so roles have no password. */
+    private get trusted();
+    connect(): Promise<void>;
+    initializeDatabase(database: string): Promise<void>;
+    /**
+     * Create the runtime app role (+ optional migrate role) and its schema, with least-privilege
+     * grants. Running it again changes nothing: each grant is made only where the role lacks it,
+     * since Postgres checks the grantor's rights even for a grant that would change nothing.
+     *
+     * The admin acts with the database owner's rights while it runs (it is made a member of the
+     * owner, and of the migrate role, only for as long as it needs to be). That is how it creates a
+     * schema and grants on it once the migrate role owns the database.
+     */
+    provisionRoles(options: ProvisionRolesOptions): Promise<void>;
+    /** @deprecated Use provisionRoles. */
+    createApiUser(username: string, password: string, database: string, _role?: string): Promise<void>;
+    private ensureRole;
+    [Symbol.asyncDispose](): Promise<void>;
+    closeConnection(): Promise<void>;
+}

package/types/src/sql-pretty.transport.d.ts

@@ -0,0 +1,2 @@
+import pinoPretty from "pino-pretty";
+export declare const SqlPretty: (opts?: any) => pinoPretty.PrettyStream;

package/types/src/type-orm.module.d.ts

@@ -0,0 +1,17 @@
+import { type DatabaseConfig } from "@decohere/data";
+import type { ContainerBuilder } from "@decohere/crucible";
+import type { ModuleConfig } from "./database-options.js";
+export type TypeOrmModuleOptions = {
+    applicationName: string;
+    databaseConfig: DatabaseConfig;
+    moduleConfigurations: ModuleConfig[];
+    containerBuilder: ContainerBuilder;
+};
+export declare class TypeOrmModule {
+    /** Registers and opens a DataSource per module. Returns the names it registered them under. */
+    configure(options: TypeOrmModuleOptions): Promise<(string | symbol)[]>;
+    private resolveDataSources;
+    private init;
+    private configureTypeOrmDataSource;
+    private getLoggerFor;
+}

package/types/src/type-orm.provider.d.ts

@@ -0,0 +1,14 @@
+import type { Entity, IDataProvider } from "@decohere/data";
+import type { Constructable } from "@decohere/core/reflection";
+import type { FindManyOptions, FindOneOptions } from "typeorm";
+import type { TypeOrmUnitOfWork } from "./unit-of-work.js";
+export declare class TypeOrmQueryProvider implements IDataProvider {
+    private unitOfWork;
+    constructor(unitOfWork: TypeOrmUnitOfWork);
+    firstOrDefault<T extends Entity>(entity: Constructable<T>, options: FindOneOptions<T>): Promise<T>;
+    all<T>(entity: Constructable, options?: FindManyOptions<T>): Promise<T[]>;
+    findById<T extends Entity>(entity: Constructable<T>, key: number | string): Promise<T>;
+    save<T>(entity: T): Promise<T>;
+    query<T extends Entity>(entity: Constructable<T>, filter: FindManyOptions<T>): Promise<T[]>;
+    delete<T>(entity: T): Promise<T>;
+}

package/types/src/type-orm.repository.d.ts

@@ -0,0 +1,12 @@
+import { type Entity, Repository } from "@decohere/data";
+import type { Constructable } from "@decohere/core/reflection";
+import type { FindOneOptions } from "typeorm";
+import { TypeOrmQueryProvider } from "./type-orm.provider.js";
+import type { TypeOrmUnitOfWork } from "./unit-of-work.js";
+export declare abstract class TypeOrmRepository<T extends Entity> extends Repository<T> {
+    protected provider: TypeOrmQueryProvider;
+    protected type: Constructable<T>;
+    constructor(unitOfWork: TypeOrmUnitOfWork, type: Constructable<T>);
+    firstOrDefault(options: FindOneOptions<T>): Promise<T | null>;
+    firstOrDefault<U extends Entity>(type: Constructable<U>, options: FindOneOptions<U>): Promise<U | null>;
+}

package/types/src/typeorm-scribe.logger.d.ts

@@ -0,0 +1,9 @@
+import type { Dialect, Provider } from "@decohere/data";
+import { AbstractLogger, type LogLevel, type LogMessage, type QueryRunner } from "typeorm";
+export declare class TypeOrmScribeLogger extends AbstractLogger {
+    private readonly logger;
+    private readonly dialect;
+    constructor(name: string, dialect: Dialect | Provider, enable?: boolean);
+    protected writeLog(level: LogLevel, logMessage: LogMessage | LogMessage[], _queryRunner?: QueryRunner): void;
+    private getLogLevel;
+}

package/types/src/typeorm.extensions.d.ts

@@ -0,0 +1,11 @@
+import { Builder } from "@decohere/http";
+import type { Logger } from "typeorm";
+import type { ModuleConfig } from "./database-options.js";
+declare module "@decohere/http" {
+    interface Builder {
+        withTypeOrm(options?: ModuleConfig[] | ModuleConfig, logger?: Logger): Builder;
+    }
+}
+export declare class BuilderExtensions {
+    static withTypeOrm(builder: Builder, config: ModuleConfig[] | ModuleConfig): Builder<import("@decohere/http").App>;
+}

package/types/src/unit-of-work.d.ts

@@ -0,0 +1,20 @@
+import type { IUnitOfWork } from "@decohere/data";
+import type { Constructable } from "@decohere/core/reflection";
+import type { DataSource, QueryRunner, Repository } from "typeorm";
+export declare class TypeOrmUnitOfWork implements IUnitOfWork {
+    private readonly dataSource;
+    readonly queryRunner: QueryRunner;
+    constructor(dataSource: DataSource);
+    get entityManager(): import("typeorm").EntityManager;
+    getRepository<T>(entity: Constructable): Repository<T>;
+    beginTransaction(): Promise<void>;
+    commit(): Promise<void>;
+    /**
+     * Hand the connection back to the pool, rolling back first if a transaction is still open
+     * (e.g. the request failed before commit). Otherwise the next user of that pooled
+     * connection would inherit the half-finished transaction (#502).
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Prefer `await using` / async disposal; this starts the same cleanup without waiting. */
+    [Symbol.dispose](): void;
+}