@aventara/prisma7-adapter 1.0.0-rc.13 → 1.0.0-rc.15

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @aventara/prisma7-adapter
 
+## 1.0.0-rc.15
+
+### Patch Changes
+
+- aab6d72: The client `avclient generate` writes now passes a default `biome check` as written, on Biome 2.4.0 and later (Biome's default rules; an opt-in rule or assist such as `useSortedKeys` is not covered): every generated file opens with `biome-ignore-all` lines for formatting, lint and import order (`organizeImports`), core's copied declarations have a blank line after their imports, the copied field-check evaluator carries no line suppression that the file-wide one makes unused, and each file ends without a final line break, which Biome 2.4.0 to 2.4.10 reported on every file under `biome-ignore-all format`. `aventara-build`'s own files pass too, in NestJS and Next.js projects: `resources.generated.ts`, `computed-fields.generated.ts` and `contracts.generated.ts` now open with the same suppressions and end without a final line break, and `--client`'s `src/aventara/client.ts` and `src/aventara/universal.ts` are written the same way. The discovery artifact `aventara-prisma7-generate` writes passes too. A file an earlier version wrote is reported stale by `aventara-build --check` and replaced by the next run. A client `avclient generate` wrote before is replaced on its next run. The client skill now says the generated files need no exclusion under Biome's default rules, and how to skip them in another linter or formatter.
+- bf98da7: A pipeline stage's types now know the root's field definitions. `aventara-build` writes `src/generated/aventara/config-facts.generated.ts` after it compiles the Contracts, and the discovery artifact puts it on the model's type:
+
+  - A Json field the root shapes reads as its shape in a stage's `ctx` calls, in `tx` and in compute's read-only `ctx`: `ctx.Product.find.many({ select: ["name"] })` types `name` as `{ ar: string; en: string }`. A read gives the shape's own type, the same as `framework.application`'s.
+  - A `VIRTUAL` field the root adds is in a variant's typed `ctx.$args` (`ctx.$args.data.tenderedMinor`), and a `ctx` create must write a non-null added input it can create.
+  - A variant's hooks and interceptors are told resolved arguments: their `ctx.$args` holds no `$ref` (an `AvTransactionReference`), since references are resolved before they run. Guards, pipes and filters still may see one.
+  - A write takes a shaped Json value read-only, deep, on every surface (`framework.application`, `ctx`, the generated client too), so a frozen value, such as a stage's `ctx.$args`, fits as well as a mutable one.
+  - A compute stage on a shaped Json field returns the shape's type. A compute stage on an added field returns the type its generated fact states, read from the model instead of the configuration. Without the generated file, its return is not typed.
+
+  The server warns at startup (`AVENTARA_STALE_GENERATED_TYPES`) when the configuration's definitions differ from the ones the generated types were written with, naming each field. It is the same one warning as for stale computed fields: one stale build gives one warning, with a paragraph for each part that is stale, including a facts file it cannot read. `aventara-build --check` also fails on a stale file. Run `aventara:prepare` after you change a `definition`.
+
+  The discovery artifact's format is now 5: regenerate it with `aventara:prepare` (an artifact of format 4 is refused, as before). The Json Shape type emitter the client generator uses now lives in `@aventara/core`; the generated clients are unchanged. The CLI's agent skill says this in `SKILL.md` and `reference/stages.md`.
+
+- Updated dependencies [aab6d72]
+- Updated dependencies [bf98da7]
+- Updated dependencies [f8cd860]
+- Updated dependencies [8a64af2]
+- Updated dependencies [548881c]
+- Updated dependencies [62fa91f]
+  - @aventara/core@1.0.0-rc.15
+
+## 1.0.0-rc.14
+
+### Patch Changes
+
+- 28688e4: On SQLite (`@prisma/adapter-better-sqlite3`), a plain operation or `ctx.$sql` that gives up waiting for the connection another request's transaction holds still answers `A3002`, and its diagnostic now says so: how many milliseconds it waited, the `maxWait` that ran out (the adapter's `transactionOptions.maxWait`, or else the PrismaClient's, 2000 ms unless set on the client), and that it never ran. A transaction that fails to open for another reason, such as an unsupported isolation level, keeps its usual diagnostic. Before, the diagnostic said the call's transaction "was no longer open", which named the wrong cause. Raise the adapter's `transactionOptions.maxWait`, or keep the transaction that holds the connection shorter.
+- Updated dependencies [1c5eaa3]
+  - @aventara/core@1.0.0-rc.14
+
 ## 1.0.0-rc.13
 
 ### Patch Changes

package/README.md

@@ -101,7 +101,8 @@ connection without waiting, so a plain call made meanwhile would run inside the
 see its uncommitted rows and roll back with it. With that driver, an operation that is not part of a
 transaction, and a `ctx.$sql` that is not, each run in a `$transaction` of their own that holds only that
 call. They wait on the driver's own lock, so operations and transactions queue for the connection and run
-one at a time. `transactionOptions` apply to the wait: past `maxWait` the operation answers `A3002`, and
+one at a time. `transactionOptions` apply to the wait: past `maxWait` the operation answers `A3002`, its
+diagnostic says how long it waited for the connection another request's transaction held, and
 `timeout` limits a single plain operation too. `@prisma/adapter-pg` checks a connection of its own out of
 the pool for each transaction, and D1 runs none, so both stay as they were. Calls made on the Prisma client
 directly, outside Aventara, are not covered.

package/dist/discovery/artifact.loader.js

@@ -50,6 +50,9 @@ function assertArtifactShape(artifact) {
     if (artifact.computedFields !== null && !isRecord(artifact.computedFields)) {
         throw new AvPrismaDiscoveryArtifactError("The discovery artifact's `computedFields` is neither a JSON object nor null.");
     }
+    if (artifact.configFacts !== null && !isRecord(artifact.configFacts)) {
+        throw new AvPrismaDiscoveryArtifactError("The discovery artifact's `configFacts` is neither a JSON object nor null.");
+    }
     for (const key of ["scalars", "enums", "resources"]) {
         if (!isRecord(artifact.model[key])) {
             throw new AvPrismaDiscoveryArtifactError(`The discovery artifact's \`model.${key}\` is not a JSON object.`);

package/dist/discovery/discovery-artifact.interface.d.ts

@@ -1,4 +1,4 @@
-import type { AvAdapterModel, AvConfigComputedFields, AvEnumDefinition, AvScalarRegistry, AvTransactionCapability } from "@aventara/core";
+import type { AvAdapter, AvAdapterModel, AvConfigComputedFields, AvEnumDefinition, AvScalarRegistry, AvTransactionCapability } from "@aventara/core";
 import type { AvAdapterResource } from "@aventara/core/internal";
 import type { AvPrismaProvider } from "../provider/provider-profile.js";
 /** The adapter model a discovery artifact carries, in Aventara's vocabulary. */
@@ -75,7 +75,7 @@ export type AvPrismaReferentialActionTable<M extends AvPrismaAdapterModel = AvPr
  */
 export type PrismaClientShape = Readonly<Record<string, readonly string[]>>;
 /** The current discovery artifact format. */
-export declare const DISCOVERY_ARTIFACT_FORMAT = 4;
+export declare const DISCOVERY_ARTIFACT_FORMAT = 5;
 /**
  * The discovery artifact: the module `aventara-prisma7-generate` writes from
  * your schema and generated client. Import its `discovery` export and pass it
@@ -118,4 +118,14 @@ export type AvPrismaDiscoveryArtifact<M extends AvPrismaAdapterModel = AvPrismaA
      * `modelHash`.
      */
     readonly computedFields: AvConfigComputedFields | null;
+    /**
+     * The Json shapes and the fields the configuration's definitions add, per
+     * Resource, as `aventara-build` read them off the Contracts it compiled (the
+     * artifact imports them when the step was given `--config`); `null` when it
+     * was given none, or the build has not compiled the Contracts yet. The
+     * model's type carries the same statement for the pipeline stages' types;
+     * this value is compared with the compiled Core Contract when the framework
+     * starts. Not part of `modelHash`.
+     */
+    readonly configFacts: NonNullable<AvAdapter["configFacts"]> | null;
 };

package/dist/discovery/discovery-artifact.interface.js

@@ -1 +1 @@
-export const DISCOVERY_ARTIFACT_FORMAT = 4;
+export const DISCOVERY_ARTIFACT_FORMAT = 5;

package/dist/errors/error.normalizer.d.ts

@@ -66,6 +66,21 @@ export declare function classifyPrismaError(error: unknown, operation: Pick<AvOp
 export declare function classifyPrismaStatementError(error: unknown): PrismaErrorClassification;
 /** The deliberate failure an `outcome` classification stands for. */
 export declare function prismaOutcomeFailure(code: AvOperationErrorCode): AvError;
+/**
+ * Whether a failure to open a transaction has the structure of the `maxWait`
+ * acquisition timeout: `P2028` with an empty `meta`.
+ */
+export declare function isPrismaAcquisitionTimeout(error: unknown): boolean;
+/**
+ * `A3002` for a plain call on a one-connection driver that gave up waiting for
+ * the connection another request's transaction held: its own transaction never
+ * opened, so `OUTCOME_MESSAGES`' "no longer open" text would name the wrong
+ * cause. Diagnostics only, like every `A3xxx` text here.
+ */
+export declare function prismaConnectionWaitFailure(facts: {
+    readonly waitedMs: number;
+    readonly maxWait: number | undefined;
+}): AvError;
 /** The `A2004` a value the database refused answers: one issue at the arguments (or the value in them) saying what was refused. */
 export declare function prismaValueFailure(refusal: PrismaValueRefusal, path?: PrismaArgumentPath): AvError;
 /** The `A2004` a nested write that writes its relation back answers: `V1012` at `path`. */

package/dist/errors/error.normalizer.js

@@ -127,6 +127,18 @@ export function prismaOutcomeFailure(code) {
         message: OUTCOME_MESSAGES[code] ?? "The operation could not be completed.",
     });
 }
+export function isPrismaAcquisitionTimeout(error) {
+    const facts = readPrismaError(error);
+    return facts.code === "P2028" && facts.metaKeys.length === 0;
+}
+export function prismaConnectionWaitFailure(facts) {
+    const limit = facts.maxWait === undefined
+        ? "the PrismaClient's maxWait (2000 ms unless set on the client)"
+        : `the adapter's maxWait (${facts.maxWait} ms)`;
+    return new AvError("A3002", {
+        message: `This call waited ${Math.round(facts.waitedMs)} ms for the SQLite connection, which another request's transaction held, and gave up when ${limit} ran out: it never ran and wrote nothing. Raise the adapter's transactionOptions.maxWait, or keep the transaction that holds the connection shorter.`,
+    });
+}
 export function prismaValueFailure(refusal, path = []) {
     const { code, message } = DATABASE_REFUSALS[refusal];
     return new AvError("A2004", {

package/dist/execution/shared-connection.router.js

@@ -1,5 +1,5 @@
 import { emitAdapterWarning } from "../adapter-warning.emitter.js";
-import { classifyPrismaStatementError, prismaOutcomeFailure, } from "../errors/error.normalizer.js";
+import { classifyPrismaStatementError, isPrismaAcquisitionTimeout, prismaConnectionWaitFailure, prismaOutcomeFailure, } from "../errors/error.normalizer.js";
 const TRANSACTION_JOINED_WARNING = "AVENTARA_PRISMA_SQLITE_TRANSACTION_JOINED";
 const warnedJoins = new Set();
 function warnJoined(call) {
@@ -40,7 +40,9 @@ export function createSharedConnectionRouter(dependencies) {
             return work(joined.client);
         }
         let thrownByWork = false;
+        let started = false;
         const run = async (transactional) => {
+            started = true;
             try {
                 return await within(transactional, () => work(transactional));
             }
@@ -50,6 +52,7 @@ export function createSharedConnectionRouter(dependencies) {
             }
         };
         const options = dependencies.transactionOptions;
+        const waitedFrom = performance.now();
         try {
             return await (options === undefined
                 ? dependencies.client.$transaction(run)
@@ -61,7 +64,14 @@ export function createSharedConnectionRouter(dependencies) {
             }
             const classification = classifyPrismaStatementError(error);
             if (classification.kind === "outcome") {
-                throw prismaOutcomeFailure(classification.code);
+                const waitedMs = performance.now() - waitedFrom;
+                const maxWait = options?.maxWait;
+                const waitedOut = !started &&
+                    isPrismaAcquisitionTimeout(error) &&
+                    (maxWait === undefined || waitedMs + 1 >= maxWait);
+                throw waitedOut
+                    ? prismaConnectionWaitFailure({ waitedMs, maxWait })
+                    : prismaOutcomeFailure(classification.code);
             }
             throw error;
         }

package/dist/generate/artifact.emitter.d.ts

@@ -20,6 +20,16 @@ type PrismaArtifactEmission = {
     readonly computedFields: {
         readonly specifier: string;
     } | null;
+    /**
+     * The specifier the module imports the configuration facts by (CORE-06
+     * step 2): the Json shapes and added fields `aventara-build` read off the
+     * Contracts it compiled (`config-facts.generated.ts`, beside the computed
+     * fields). `null` when the step was given no configuration: the module then
+     * states none. Beside `model`, outside the hash.
+     */
+    readonly configFacts: {
+        readonly specifier: string;
+    } | null;
 };
 export declare function emitDiscoveryArtifactModule(emission: PrismaArtifactEmission): Promise<string>;
 export {};

package/dist/generate/artifact.emitter.js

@@ -4,6 +4,7 @@ import { DISCOVERY_ARTIFACT_FORMAT, } from "../discovery/discovery-artifact.inte
 const BANNER = [
     "// biome-ignore-all format: generated output",
     "// biome-ignore-all lint: generated output",
+    "// biome-ignore-all assist/source/organizeImports: generated output",
     "/* !!! Generated by @aventara/prisma7-adapter's generate step. Do not edit. !!! */",
     "/* Regenerate with `aventara-prisma7-generate`. */",
 ];
@@ -74,6 +75,22 @@ const NO_COMPUTED_FIELDS_DOC = [
     " * `modelHash`.",
     " */",
 ];
+const CONFIG_FACTS_DOC = [
+    "/**",
+    " * The Json shapes and the fields the configuration's definitions add, per",
+    " * Resource, as aventara-build read them off the Contracts it compiled. A",
+    " * pipeline stage's `ctx` and its arguments are typed with them. The framework",
+    " * warns at startup when the configuration says otherwise: run",
+    " * `aventara:prepare` again. Not part of `modelHash`.",
+    " */",
+];
+const NO_CONFIG_FACTS_DOC = [
+    "/**",
+    " * `null`: the generate step was given no configuration (`--config`), so",
+    " * pipeline stages see the model's own fields, Json unshaped. Not part of",
+    " * `modelHash`.",
+    " */",
+];
 const DISCOVERY_DOC = [
     "/** Pass this to `createPrismaAdapter({ discovery })`. */",
 ];
@@ -94,6 +111,46 @@ function computedFieldsLines(computedFields) {
         "",
     ];
 }
+function configFactsLines(configFacts) {
+    if (configFacts === null) {
+        return [...NO_CONFIG_FACTS_DOC, "export const configFacts = null;", ""];
+    }
+    return [
+        ...CONFIG_FACTS_DOC,
+        "export { type AvConfigFacts, configFacts };",
+        "",
+    ];
+}
+function generatedStatementLines(emission) {
+    if (emission.computedFields !== null && emission.configFacts !== null) {
+        return [
+            ...COMPUTED_FIELDS_DOC,
+            ...CONFIG_FACTS_DOC,
+            "export {",
+            "\ttype AvComputedFields,",
+            "\ttype AvConfigFacts,",
+            "\tcomputedFields,",
+            "\tconfigFacts,",
+            "};",
+            "",
+        ];
+    }
+    return [
+        ...computedFieldsLines(emission.computedFields),
+        ...configFactsLines(emission.configFacts),
+    ];
+}
+function modelTypeMembers(emission) {
+    const members = [
+        ...(emission.computedFields === null
+            ? []
+            : ['readonly "~computedFields"?: AvComputedFields']),
+        ...(emission.configFacts === null
+            ? []
+            : ['readonly "~configFacts"?: AvConfigFacts']),
+    ];
+    return members.length === 0 ? "};" : `} & { ${members.join("; ")} };`;
+}
 export async function emitDiscoveryArtifactModule(emission) {
     const modelHash = await computeModelHash(emission.model);
     return `${[
@@ -105,16 +162,19 @@ export async function emitDiscoveryArtifactModule(emission) {
             : [
                 `import { type AvComputedFields, computedFields } from ${JSON.stringify(emission.computedFields.specifier)};`,
             ]),
+        ...(emission.configFacts === null
+            ? []
+            : [
+                `import { type AvConfigFacts, configFacts } from ${JSON.stringify(emission.configFacts.specifier)};`,
+            ]),
         "",
         `const discoveredModel = ${canonicalLiteral(emission.model)} as const satisfies AvAdapterModel;`,
         "",
-        ...computedFieldsLines(emission.computedFields),
+        ...generatedStatementLines(emission),
         ...MODEL_TYPE_DOC,
         "export type AvModel = {",
         "\treadonly [K in keyof typeof discoveredModel]: (typeof discoveredModel)[K];",
-        emission.computedFields === null
-            ? "};"
-            : '} & { readonly "~computedFields"?: AvComputedFields };',
+        modelTypeMembers(emission),
         "",
         ...MODEL_DOC,
         "export const model: AvModel = discoveredModel;",
@@ -143,6 +203,7 @@ export async function emitDiscoveryArtifactModule(emission) {
         "\treferentialActions,",
         "\tclient,",
         "\tcomputedFields,",
+        "\tconfigFacts,",
         "} as const;",
-    ].join("\n")}\n`;
+    ].join("\n")}`;
 }

package/dist/generate/computed-fields.import.d.ts

@@ -3,3 +3,8 @@
  * the sibling `computed-fields.generated` module.
  */
 export declare function computedFieldsSpecifier(artifactFile: string): string;
+/**
+ * The specifier the artifact at `artifactFile` imports the configuration
+ * facts by: the sibling `config-facts.generated` module.
+ */
+export declare function configFactsSpecifier(artifactFile: string): string;

package/dist/generate/computed-fields.import.js

@@ -50,3 +50,6 @@ function importSuffix(directory) {
 export function computedFieldsSpecifier(artifactFile) {
     return `./computed-fields.generated${importSuffix(path.dirname(path.resolve(artifactFile)))}`;
 }
+export function configFactsSpecifier(artifactFile) {
+    return `./config-facts.generated${importSuffix(path.dirname(path.resolve(artifactFile)))}`;
+}

package/dist/generate/prisma.generate.js

@@ -7,7 +7,7 @@ import { computeModelHash } from "../discovery/artifact.loader.js";
 import { AvPrismaSchemaReaderError, readPrismaSchema, } from "../discovery/schema.reader.js";
 import { readPrismaCapabilitySurface } from "../discovery/types.reader.js";
 import { emitDiscoveryArtifactModule } from "./artifact.emitter.js";
-import { computedFieldsSpecifier } from "./computed-fields.import.js";
+import { computedFieldsSpecifier, configFactsSpecifier, } from "./computed-fields.import.js";
 import { readDeclaredSupport } from "./declared-support.reader.js";
 import { applyExistenceGate } from "./existence.gate.js";
 import { resolvePrismaCli } from "./prisma-cli.resolver.js";
@@ -230,6 +230,9 @@ export async function runPrismaGenerateStep(request) {
             : {
                 specifier: computedFieldsSpecifier(request.artifactFile),
             },
+        configFacts: request.config === undefined
+            ? null
+            : { specifier: configFactsSpecifier(request.artifactFile) },
     });
     await toolchain.writeArtifact(request.artifactFile, source);
     return {

package/dist/prisma-adapter.description.d.ts

@@ -11,7 +11,7 @@ type PrismaAdapterDescriptionInput<M extends AvPrismaAdapterModel> = {
     readonly driver: AvPrismaDriver;
 };
 /** The adapter's passive facts, as {@link describePrismaAdapter} states them. */
-type PrismaAdapterDescription<M extends AvPrismaAdapterModel> = PrismaAdapterDescriptionInput<M> & Required<Pick<AvAdapter<M>, "model" | "referentialActions">> & Pick<AvAdapter<M>, "computedFields"> & {
+type PrismaAdapterDescription<M extends AvPrismaAdapterModel> = PrismaAdapterDescriptionInput<M> & Required<Pick<AvAdapter<M>, "model" | "referentialActions">> & Pick<AvAdapter<M>, "computedFields" | "configFacts"> & {
     /**
      * The driver's transaction capability: `"interactive"` when the
      * constructed Adapter runs transactions, `"none"` when it carries no

package/dist/prisma-adapter.description.js

@@ -23,6 +23,7 @@ export function describePrismaAdapter(input) {
         driver: input.driver,
     });
     const computedFields = input.discovery.computedFields;
+    const configFacts = input.discovery.configFacts;
     return Object.freeze({
         discovery: input.discovery,
         provider: input.provider,
@@ -31,6 +32,7 @@ export function describePrismaAdapter(input) {
         transactions: profile.transactions,
         referentialActions: translateReferentialActions(input.discovery.referentialActions),
         ...(computedFields === null ? {} : { computedFields }),
+        ...(configFacts === null ? {} : { configFacts }),
         sqlStatements: true,
     });
 }

package/dist/prisma.adapter.js

@@ -34,9 +34,14 @@ export async function createPrismaAdapter(options) {
     const referentialActions = description.referentialActions;
     const backReferences = derivePrismaBackReferences(options.discovery.model);
     const bigintBinding = resolveBigintBinding(options.driver);
-    const computedFields = description.computedFields === undefined
-        ? {}
-        : { computedFields: description.computedFields };
+    const generatedTypeFacts = {
+        ...(description.computedFields === undefined
+            ? {}
+            : { computedFields: description.computedFields }),
+        ...(description.configFacts === undefined
+            ? {}
+            : { configFacts: description.configFacts }),
+    };
     const translation = options.discovery.translation;
     const transactionOptions = options.transactionOptions === undefined
         ? {}
@@ -73,7 +78,7 @@ export async function createPrismaAdapter(options) {
         return {
             model,
             referentialActions,
-            ...computedFields,
+            ...generatedTypeFacts,
             execute,
             sqlStatements: description.sqlStatements,
             executeSql,
@@ -91,7 +96,7 @@ export async function createPrismaAdapter(options) {
     return {
         model,
         referentialActions,
-        ...computedFields,
+        ...generatedTypeFacts,
         execute,
         transaction,
         sqlStatements: description.sqlStatements,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/prisma7-adapter",
-  "version": "1.0.0-rc.13",
+  "version": "1.0.0-rc.15",
   "license": "SEE LICENSE IN LICENSE",
   "description": "The Prisma 7 adapter for Aventara.",
   "type": "module",
@@ -30,7 +30,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/core": "1.0.0-rc.13"
+    "@aventara/core": "1.0.0-rc.15"
   },
   "peerDependencies": {
     "@prisma/adapter-better-sqlite3": "^7.10.1",