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

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @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

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/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.14",
+  "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.14"
+    "@aventara/core": "1.0.0-rc.15"
   },
   "peerDependencies": {
     "@prisma/adapter-better-sqlite3": "^7.10.1",