@geekmidas/constructs 10.0.0-alpha.12 → 10.0.0-alpha.120

package/dist/kysely-BHYV-WC-.d.cts

@@ -0,0 +1,216 @@
+import { n as Construct } from "./construct-interface-B1AfqRl4.cjs";
+import { t as Cache } from "./cache-DnGDGly3.cjs";
+import { Service } from "@geekmidas/services";
+import { ConstructName, Declaration, PostgresVersion } from "@geekmidas/manifest";
+import { Kysely, KyselyConfig } from "kysely";
+import "pg";
+//#region src/database/pool.d.ts
+/**
+ * End every pool opened, waiting for checked-out connections to come back.
+ * For a server's shutdown, after it has stopped taking requests.
+ */
+declare function closeDatabasePools(): Promise<void>;
+//#endregion
+//#region src/database/kysely.d.ts
+/**
+ * Everything Kysely takes, plus what this construct declares.
+ *
+ * `dialect` is omitted because the construct owns it — it is built from the one
+ * URL the adapter supplied, which is the whole point of the construct. The rest
+ * of `KyselyConfig` (`plugins`, `log`) is the app's business and passes
+ * straight through, so anything Kysely adds later arrives without being
+ * tracked here.
+ */
+interface KyselyDatabaseBaseOptions extends Omit<KyselyConfig, 'dialect'> {
+  /**
+   * The schema, pinned on both roles' `search_path`.
+   *
+   * Defaults to `app` — the role the schema plays, rather than a restatement
+   * of the database's own name, which reads correctly beside `auth` and
+   * `pgboss` and keeps the application off `public`.
+   */
+  schema?: string;
+  /**
+   * Provision the owner/runtime role split. Defaults to on.
+   *
+   * Off falls back to the cluster's master credential in both URLs, giving up
+   * the DDL/DML split and putting credentials that can drop a table into the
+   * function's environment. A deliberate downgrade, not a default.
+   */
+  roles?: boolean;
+  /**
+   * Extensions to create in this database, as the cluster master, before the
+   * first migration — for the ones the owner role a migration runs as may not
+   * create (PostGIS is not a trusted extension). They are created in
+   * `public`, which joins this database's roles' `search_path`, so their
+   * types resolve unqualified.
+   *
+   * Only attempted: the image has to ship them.
+   */
+  extensions?: readonly string[];
+  /**
+   * End each query run inside a request with a comment naming what ran it —
+   * `/*operation='POST /orders',request_id='…'*\/` — so `pg_stat_activity`
+   * and the server's logs can tie a query to its endpoint — and, inside a
+   * trace, with the query span's `traceparent='00-…'` (sqlcommenter), so
+   * they can tie it to the trace too. Defaults to on.
+   */
+  queryTags?: boolean;
+}
+/**
+ * Which Postgres the database runs: a major on the stock image, or an image
+ * the project names. One or the other, never both — an image's tag already
+ * says its major, and a second statement of it is one that can disagree.
+ */
+type PostgresRuntime = {
+  /**
+   * The Postgres major version to provision, on the stock image.
+   *
+   * Declared here so one statement reaches every target. It was
+   * previously set in two unrelated places — a container tag locally,
+   * nothing at all on AWS (so Aurora chose) — which is how local came to
+   * run 18 while deployed ran 17.7 with nothing recording the difference.
+   *
+   * Defaults to {@link DEFAULT_POSTGRES_VERSION}.
+   */
+  version?: PostgresVersion;
+  image?: never;
+} | {
+  /**
+   * The container image to run, wherever a target runs one (local,
+   * Dokploy), in place of `postgres:<version>`.
+   *
+   * Yours to choose and used as written: its tag is the major, and it
+   * should ship every extension in `extensions`. AWS runs RDS, ignores
+   * it, and provisions {@link DEFAULT_POSTGRES_VERSION}.
+   *
+   * ```ts
+   * new KyselyDatabase<GeoDB>('Geo', {
+   *   image: 'postgis/postgis:18-3.6-alpine',
+   *   extensions: ['postgis'],
+   * });
+   * ```
+   */
+  image: string;
+  version?: never;
+};
+/**
+ * Everything Kysely takes, plus what this construct declares — including
+ * which Postgres it runs, as a version or an image.
+ */
+type KyselyDatabaseOptions = KyselyDatabaseBaseOptions & PostgresRuntime;
+/** What makes a construct derived rather than a database in its own right. */
+interface DerivedFrom {
+  kind: 'database-reader' | 'database-schema';
+  of: string;
+  schema?: string;
+}
+/**
+ * @typeParam DB - the database's schema.
+ * @typeParam TName - the canonical id. TypeScript has no partial
+ * type-argument inference, so `new KyselyDatabase<OrdersDB>('orders')` leaves
+ * this at its default and the service key widens to `string`. `db` still types
+ * through `.database()`, which infers from the service.
+ */
+declare class KyselyDatabase<DB = unknown, TName extends string = string> implements Construct<TName, Kysely<DB>> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, Kysely<DB>>;
+  /**
+   * Declared once and read by both `declare()` and `connect()`, so the key the
+   * build publishes and the key the client reads cannot drift.
+   */
+  private readonly config;
+  private readonly schemaName;
+  private readonly roles;
+  private readonly runtime;
+  private readonly derivedFrom?;
+  constructor(id: ConstructName<TName>, options?: KyselyDatabaseOptions, derivedFrom?: DerivedFrom);
+  declare(): Declaration[];
+  /**
+   * A read-only endpoint on this database.
+   *
+   * Read-only is enforced by the reader role's grants rather than by which
+   * endpoint it resolves to, so falling back to the writer where no replica
+   * exists is safe rather than a silently writable connection behind a name
+   * that says reader. There is no `writer()`: the database *is* the writer, so
+   * a replica can never be reached by accident.
+   *
+   * The return type is narrower than this class on purpose — see
+   * {@link ReadOnlyDatabase}.
+   */
+  reader(): ReadOnlyDatabase<DB, `${TName}Reader`>;
+  /**
+   * A cache that lives in this database.
+   *
+   * The same strengthening `schema()` is over a second database: `new
+   * Cache('Sessions')` says the app caches and leaves where to the deployment,
+   * while this says it caches *here* — which is a fact about the application
+   * and so belongs in its code.
+   *
+   * What it buys beyond being explicit: the table's schema and the role that
+   * reaches it come from this database rather than from a second convention,
+   * and the backend no longer has to guess which database "the database" meant
+   * when an app declares two.
+   *
+   * A cache is not a `KyselyDatabase`, so this returns a `Cache` — the client
+   * is a key/value store, not a query builder, and typing it as the parent
+   * would be a convenience that lies.
+   */
+  cache<TCache extends string = `${TName}Cache`>(id?: ConstructName<TCache>, options?: {
+    table?: string;
+  }): Cache<TCache>;
+  /**
+   * A second schema in this database, with its own role(s) and its own URL —
+   * so this database's role holds no grant on those tables at all.
+   *
+   * Typed separately because a tenant has its own tables: the point is that
+   * `auth.selectFrom('sessions')` type-checks and
+   * `orders.selectFrom('sessions')` does not.
+   */
+  schema<TenantDB, TTenant extends string>(id: ConstructName<TTenant>, options?: KyselyDatabaseOptions): KyselyDatabase<TenantDB, TTenant>;
+  /**
+   * A connection as the *owner* role — the one that may create, alter and drop.
+   *
+   * A `Service` rather than part of the construct, and deliberately so: a
+   * construct is what `.dependsOn()` accepts, and nothing should be able to
+   * depend on this. A migrator asks for it by name; a handler cannot ask at
+   * all, which is the security property the role split exists for.
+   *
+   * Falls back to the runtime URL where no owner URL was published — the
+   * `roles: false` downgrade, where there is only one credential and it is the
+   * cluster master's.
+   */
+  get owner(): Service<`${Uncapitalize<TName>}Owner`, Kysely<DB>>;
+  /**
+   * What this database's clients are built with besides a dialect — the
+   * plugins and logging it was declared with.
+   *
+   * Public so that whatever opens a connection to it outside \`connect()\` —
+   * a test's transaction — builds the same client. A test that dropped the
+   * plugins would write \`createdAt\` where production writes \`created_at\`.
+   */
+  get clientConfig(): Omit<KyselyConfig, 'dialect'>;
+  private connect;
+}
+/**
+ * A database you may read through, and derive nothing from.
+ *
+ * A reader is terminal in the graph, and this is that fact in the type system.
+ * `DERIVES_FROM` gives `cache` and `database-schema` no `database-reader`
+ * parent, and there is no reader of a reader — so `orders.reader().cache(…)`
+ * has always been illegal, but it type-checked and failed later at
+ * `assertDerivations`. That is a long way round to learn that a read-only
+ * endpoint cannot own a table something writes to.
+ *
+ * Omitting the three deriving methods rather than making them throw keeps the
+ * failure where it costs least: the editor, on the line that wrote it.
+ *
+ * The result is deliberately not assignable back to `KyselyDatabase` — a
+ * reader is not one, and anything that genuinely needs the writer should say
+ * so.
+ */
+type ReadOnlyDatabase<DB, TName extends string> = Omit<KyselyDatabase<DB, TName>, 'reader' | 'cache' | 'schema'>;
+//#endregion
+export { closeDatabasePools as a, ReadOnlyDatabase as i, KyselyDatabaseOptions as n, PostgresRuntime as r, KyselyDatabase as t };
+//# sourceMappingURL=kysely-BHYV-WC-.d.cts.map

package/dist/kysely-BHYV-WC-.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely-BHYV-WC-.d.cts","names":[],"sources":["../src/database/pool.ts","../src/database/kysely.ts"],"mappings":";;;;;;;;;;;iBAwGsB,sBAAsB;;;;;;;;;;;;UChElC,kCAAkC,KAAK;;;;;;;;EAQhD;;;;;;;;EAQA;;;;;;;;;;EAUA;;;;;;;;EAQA;;;;;;;KAQW;;;;;;;;;;;EAYT,UAAU;EACV;;;;;;;;;;;;;;;;;EAkBA;EACA;;;;;;KAOS,wBAAwB,4BAA4B;;UAGtD;EACT;EACA;EACA;;;;;;;;;cAUY,eAAe,cAAc,0CAC9B,UAAU,OAAO,OAAO;mBAiBjB;WAfT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,OAAO;;;;;mBAMrC;mBACA;mBACA;mBACA;mBACA;EAEjB,YACC,IAAI,cAAc,QACD,UAAS,uBAC1B,cAAc;EA2Bf,WAAW;;;;;;;;;;;;;EAyDX,UAAU,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;EAyBlC,MAAM,2BAA2B,cAChC,KAAI,cAAc,SAClB;IAAW;MACT,MAAM;;;;;;;;;EAeT,OAAO,UAAU,wBAChB,IAAI,cAAc,UAClB,UAAS,wBACP,eAAe,UAAU;;;;;;;;;;;;;MAoBxB,SAAS,WAAW,aAAa,eAAe,OAAO;;;;;;;;;MAgBvD,gBAAgB,KAAK;UAiBX;;;;;;;;;;;;;;;;;;;KAuCH,iBAAiB,IAAI,wBAAwB,KACxD,eAAe,IAAI"}

package/dist/kysely-CAW3QSqp.d.mts

@@ -0,0 +1,216 @@
+import { n as Construct } from "./construct-interface-ZvYQbivO.mjs";
+import { t as Cache } from "./cache-5QZzh5Er.mjs";
+import { ConstructName, Declaration, PostgresVersion } from "@geekmidas/manifest";
+import { Service } from "@geekmidas/services";
+import { Kysely, KyselyConfig } from "kysely";
+import pg from "pg";
+//#region src/database/pool.d.ts
+/**
+ * End every pool opened, waiting for checked-out connections to come back.
+ * For a server's shutdown, after it has stopped taking requests.
+ */
+declare function closeDatabasePools(): Promise<void>;
+//#endregion
+//#region src/database/kysely.d.ts
+/**
+ * Everything Kysely takes, plus what this construct declares.
+ *
+ * `dialect` is omitted because the construct owns it — it is built from the one
+ * URL the adapter supplied, which is the whole point of the construct. The rest
+ * of `KyselyConfig` (`plugins`, `log`) is the app's business and passes
+ * straight through, so anything Kysely adds later arrives without being
+ * tracked here.
+ */
+interface KyselyDatabaseBaseOptions extends Omit<KyselyConfig, 'dialect'> {
+  /**
+   * The schema, pinned on both roles' `search_path`.
+   *
+   * Defaults to `app` — the role the schema plays, rather than a restatement
+   * of the database's own name, which reads correctly beside `auth` and
+   * `pgboss` and keeps the application off `public`.
+   */
+  schema?: string;
+  /**
+   * Provision the owner/runtime role split. Defaults to on.
+   *
+   * Off falls back to the cluster's master credential in both URLs, giving up
+   * the DDL/DML split and putting credentials that can drop a table into the
+   * function's environment. A deliberate downgrade, not a default.
+   */
+  roles?: boolean;
+  /**
+   * Extensions to create in this database, as the cluster master, before the
+   * first migration — for the ones the owner role a migration runs as may not
+   * create (PostGIS is not a trusted extension). They are created in
+   * `public`, which joins this database's roles' `search_path`, so their
+   * types resolve unqualified.
+   *
+   * Only attempted: the image has to ship them.
+   */
+  extensions?: readonly string[];
+  /**
+   * End each query run inside a request with a comment naming what ran it —
+   * `/*operation='POST /orders',request_id='…'*\/` — so `pg_stat_activity`
+   * and the server's logs can tie a query to its endpoint — and, inside a
+   * trace, with the query span's `traceparent='00-…'` (sqlcommenter), so
+   * they can tie it to the trace too. Defaults to on.
+   */
+  queryTags?: boolean;
+}
+/**
+ * Which Postgres the database runs: a major on the stock image, or an image
+ * the project names. One or the other, never both — an image's tag already
+ * says its major, and a second statement of it is one that can disagree.
+ */
+type PostgresRuntime = {
+  /**
+   * The Postgres major version to provision, on the stock image.
+   *
+   * Declared here so one statement reaches every target. It was
+   * previously set in two unrelated places — a container tag locally,
+   * nothing at all on AWS (so Aurora chose) — which is how local came to
+   * run 18 while deployed ran 17.7 with nothing recording the difference.
+   *
+   * Defaults to {@link DEFAULT_POSTGRES_VERSION}.
+   */
+  version?: PostgresVersion;
+  image?: never;
+} | {
+  /**
+   * The container image to run, wherever a target runs one (local,
+   * Dokploy), in place of `postgres:<version>`.
+   *
+   * Yours to choose and used as written: its tag is the major, and it
+   * should ship every extension in `extensions`. AWS runs RDS, ignores
+   * it, and provisions {@link DEFAULT_POSTGRES_VERSION}.
+   *
+   * ```ts
+   * new KyselyDatabase<GeoDB>('Geo', {
+   *   image: 'postgis/postgis:18-3.6-alpine',
+   *   extensions: ['postgis'],
+   * });
+   * ```
+   */
+  image: string;
+  version?: never;
+};
+/**
+ * Everything Kysely takes, plus what this construct declares — including
+ * which Postgres it runs, as a version or an image.
+ */
+type KyselyDatabaseOptions = KyselyDatabaseBaseOptions & PostgresRuntime;
+/** What makes a construct derived rather than a database in its own right. */
+interface DerivedFrom {
+  kind: 'database-reader' | 'database-schema';
+  of: string;
+  schema?: string;
+}
+/**
+ * @typeParam DB - the database's schema.
+ * @typeParam TName - the canonical id. TypeScript has no partial
+ * type-argument inference, so `new KyselyDatabase<OrdersDB>('orders')` leaves
+ * this at its default and the service key widens to `string`. `db` still types
+ * through `.database()`, which infers from the service.
+ */
+declare class KyselyDatabase<DB = unknown, TName extends string = string> implements Construct<TName, Kysely<DB>> {
+  private readonly options;
+  readonly id: TName;
+  readonly service: Service<Uncapitalize<TName>, Kysely<DB>>;
+  /**
+   * Declared once and read by both `declare()` and `connect()`, so the key the
+   * build publishes and the key the client reads cannot drift.
+   */
+  private readonly config;
+  private readonly schemaName;
+  private readonly roles;
+  private readonly runtime;
+  private readonly derivedFrom?;
+  constructor(id: ConstructName<TName>, options?: KyselyDatabaseOptions, derivedFrom?: DerivedFrom);
+  declare(): Declaration[];
+  /**
+   * A read-only endpoint on this database.
+   *
+   * Read-only is enforced by the reader role's grants rather than by which
+   * endpoint it resolves to, so falling back to the writer where no replica
+   * exists is safe rather than a silently writable connection behind a name
+   * that says reader. There is no `writer()`: the database *is* the writer, so
+   * a replica can never be reached by accident.
+   *
+   * The return type is narrower than this class on purpose — see
+   * {@link ReadOnlyDatabase}.
+   */
+  reader(): ReadOnlyDatabase<DB, `${TName}Reader`>;
+  /**
+   * A cache that lives in this database.
+   *
+   * The same strengthening `schema()` is over a second database: `new
+   * Cache('Sessions')` says the app caches and leaves where to the deployment,
+   * while this says it caches *here* — which is a fact about the application
+   * and so belongs in its code.
+   *
+   * What it buys beyond being explicit: the table's schema and the role that
+   * reaches it come from this database rather than from a second convention,
+   * and the backend no longer has to guess which database "the database" meant
+   * when an app declares two.
+   *
+   * A cache is not a `KyselyDatabase`, so this returns a `Cache` — the client
+   * is a key/value store, not a query builder, and typing it as the parent
+   * would be a convenience that lies.
+   */
+  cache<TCache extends string = `${TName}Cache`>(id?: ConstructName<TCache>, options?: {
+    table?: string;
+  }): Cache<TCache>;
+  /**
+   * A second schema in this database, with its own role(s) and its own URL —
+   * so this database's role holds no grant on those tables at all.
+   *
+   * Typed separately because a tenant has its own tables: the point is that
+   * `auth.selectFrom('sessions')` type-checks and
+   * `orders.selectFrom('sessions')` does not.
+   */
+  schema<TenantDB, TTenant extends string>(id: ConstructName<TTenant>, options?: KyselyDatabaseOptions): KyselyDatabase<TenantDB, TTenant>;
+  /**
+   * A connection as the *owner* role — the one that may create, alter and drop.
+   *
+   * A `Service` rather than part of the construct, and deliberately so: a
+   * construct is what `.dependsOn()` accepts, and nothing should be able to
+   * depend on this. A migrator asks for it by name; a handler cannot ask at
+   * all, which is the security property the role split exists for.
+   *
+   * Falls back to the runtime URL where no owner URL was published — the
+   * `roles: false` downgrade, where there is only one credential and it is the
+   * cluster master's.
+   */
+  get owner(): Service<`${Uncapitalize<TName>}Owner`, Kysely<DB>>;
+  /**
+   * What this database's clients are built with besides a dialect — the
+   * plugins and logging it was declared with.
+   *
+   * Public so that whatever opens a connection to it outside \`connect()\` —
+   * a test's transaction — builds the same client. A test that dropped the
+   * plugins would write \`createdAt\` where production writes \`created_at\`.
+   */
+  get clientConfig(): Omit<KyselyConfig, 'dialect'>;
+  private connect;
+}
+/**
+ * A database you may read through, and derive nothing from.
+ *
+ * A reader is terminal in the graph, and this is that fact in the type system.
+ * `DERIVES_FROM` gives `cache` and `database-schema` no `database-reader`
+ * parent, and there is no reader of a reader — so `orders.reader().cache(…)`
+ * has always been illegal, but it type-checked and failed later at
+ * `assertDerivations`. That is a long way round to learn that a read-only
+ * endpoint cannot own a table something writes to.
+ *
+ * Omitting the three deriving methods rather than making them throw keeps the
+ * failure where it costs least: the editor, on the line that wrote it.
+ *
+ * The result is deliberately not assignable back to `KyselyDatabase` — a
+ * reader is not one, and anything that genuinely needs the writer should say
+ * so.
+ */
+type ReadOnlyDatabase<DB, TName extends string> = Omit<KyselyDatabase<DB, TName>, 'reader' | 'cache' | 'schema'>;
+//#endregion
+export { closeDatabasePools as a, ReadOnlyDatabase as i, KyselyDatabaseOptions as n, PostgresRuntime as r, KyselyDatabase as t };
+//# sourceMappingURL=kysely-CAW3QSqp.d.mts.map

package/dist/kysely-CAW3QSqp.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely-CAW3QSqp.d.mts","names":[],"sources":["../src/database/pool.ts","../src/database/kysely.ts"],"mappings":";;;;;;;;;;;iBAwGsB,sBAAsB;;;;;;;;;;;;UChElC,kCAAkC,KAAK;;;;;;;;EAQhD;;;;;;;;EAQA;;;;;;;;;;EAUA;;;;;;;;EAQA;;;;;;;KAQW;;;;;;;;;;;EAYT,UAAU;EACV;;;;;;;;;;;;;;;;;EAkBA;EACA;;;;;;KAOS,wBAAwB,4BAA4B;;UAGtD;EACT;EACA;EACA;;;;;;;;;cAUY,eAAe,cAAc,0CAC9B,UAAU,OAAO,OAAO;mBAiBjB;WAfT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,OAAO;;;;;mBAMrC;mBACA;mBACA;mBACA;mBACA;EAEjB,YACC,IAAI,cAAc,QACD,UAAS,uBAC1B,cAAc;EA2Bf,WAAW;;;;;;;;;;;;;EAyDX,UAAU,iBAAiB,OAAO;;;;;;;;;;;;;;;;;;EAyBlC,MAAM,2BAA2B,cAChC,KAAI,cAAc,SAClB;IAAW;MACT,MAAM;;;;;;;;;EAeT,OAAO,UAAU,wBAChB,IAAI,cAAc,UAClB,UAAS,wBACP,eAAe,UAAU;;;;;;;;;;;;;MAoBxB,SAAS,WAAW,aAAa,eAAe,OAAO;;;;;;;;;MAgBvD,gBAAgB,KAAK;UAiBX;;;;;;;;;;;;;;;;;;;KAuCH,iBAAiB,IAAI,wBAAwB,KACxD,eAAe,IAAI"}