@aventara/build 1.0.0-rc.13 → 1.0.0-rc.14

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @aventara/build
 
+## 1.0.0-rc.14
+
+### Patch Changes
+
+- 0895a93: `avDehydrate` and `avHydrate` are typed: data handed from a Server Component to a Client Component as props keeps its type, with no cast.
+
+  - `avDehydrate(data)` (`@aventara/next`) returns an `AvDehydrated<T>` for data of type `T`, and `avHydrate(value)` (`@/aventara/client`) of an `AvDehydrated<T>` returns the `T`, its `Date`, `bigint`, `Uint8Array` and `AvDecimal` values included. Type an SWR `fallback` prop `AvDehydrated<T>` and pass `avHydrate(fallback)` to `SWRConfig` as it is.
+  - `AvDehydrated<T>` is new, exported by `@aventara/next` and by the `src/aventara/client.ts` that `aventara-build --client` writes; the two are one type. It is opaque: a plain object, the data itself, or the dehydrated form of another type is a compile error where an `AvDehydrated<T>` is expected.
+  - A Resource or enum named `AvDehydrated` or `avHydrate` is now emitted under a renamed identifier (`AvDehydratedModel`, `avHydrateModel`), with a warning, as other names the generated client owns are. Before, `src/aventara/client.ts`'s own declaration hid a Resource type of that name, which could not be imported from it.
+  - Read data you dehydrate through `@/aventara/universal`: `@/aventara/server` types a decimal as core's `AvDecimal`, while `avHydrate` revives it as the browser client's.
+  - Pass `avHydrate(fallback)` to `SWRConfig`, never the dehydrated value itself: SWR's `fallback` is typed `any`, so the compiler cannot catch it.
+  - `avHydrate` still takes `unknown` and returns `unknown`; `avDehydrate` of an `unknown` value returns an `AvDehydrated<unknown>`. `serializeData: avDehydrate` and `deserializeData: avHydrate` in TanStack Query are written as before.
+  - The agent skills show the SWR props pattern typed, with no cast. The frontend skill's refresh line no longer names `npx`, and says a file you edited is kept with a warning naming it, and replaced with `--force`.
+
+- Updated dependencies [1c5eaa3]
+- Updated dependencies [0895a93]
+  - @aventara/core@1.0.0-rc.14
+  - @aventara/client@1.0.0-rc.14
+
 ## 1.0.0-rc.13
 
 ### Minor Changes

package/README.md

@@ -135,7 +135,7 @@ so no running server is needed:
 
 | File | What it holds |
 |---|---|
-| `src/aventara/client.ts` | `avClient`, the typed client calling the app's own `api` (`/api`) from the browser, and `avHydrate`; and every name `avclient generate`'s `AvClient.ts` exports besides its default: `AvClient`, the Resource types, the enums, `AvDecimal` and the error classes |
+| `src/aventara/client.ts` | `avClient`, the typed client calling the app's own `api` (`/api`) from the browser, `avHydrate` and its `AvDehydrated<T>` type; and every name `avclient generate`'s `AvClient.ts` exports besides its default: `AvClient`, the Resource types, the enums, `AvDecimal` and the error classes |
 | `src/aventara/universal.ts` | `avClient` for both sides: in the browser it calls the app's own `api`, on the server it calls the app in process, through what `ready()` from `@aventara/next` registers in `src/instrumentation.ts`, with that request's state |
 | `src/aventara/generated/` (the client's modules) | the same modules `avclient generate` writes for the same ClientContract, but with the app's own `api` as the entrypoint, and saying to regenerate them with `aventara-build --client` |
 

package/dist/client/client-file.js

@@ -152,7 +152,7 @@ function optionsImport(options) {
 }
 function entrySource(style, accessVerbs, options) {
     const from = (module) => JSON.stringify(importSpecifier(module, style));
-    const { tagKey, valueKey, objectTag, scalarTags } = HYDRATION_FORMAT;
+    const { tagKey, valueKey, objectTag, scalarTags, typeKey } = HYDRATION_FORMAT;
     const tagged = [...scalarTags, objectTag]
         .map((tag) => JSON.stringify(tag))
         .join(" | ");
@@ -221,17 +221,35 @@ function revivedMembers(record: Readonly<Record<string, unknown>>): Record<strin
 	return Object.fromEntries(Object.entries(record).map(([key, member]) => [key, avHydrate(member)]));
 }
 
+/**
+ * Data of type \`T\` as \`avDehydrate\` (from \`@aventara/next\`) sends it from the
+ * server: opaque, read back as the \`T\` by \`avHydrate\`. Type a Client
+ * Component's prop with it to take server data with no cast. It is
+ * \`@aventara/next\`'s \`AvDehydrated\`, declared here again: its one member is a
+ * brand of the type only, never of the value.
+ */
+export type AvDehydrated<T> = {
+	/** The type the value was dehydrated from: the type's brand, no member of the value. */
+	readonly ${JSON.stringify(typeKey)}: T;
+};
+
 /**
  * Revives data that \`avDehydrate\` (from \`@aventara/next\`) made safe to pass
  * from the server to the browser: each tagged Date, bigint, Uint8Array and
  * decimal becomes the value this client reads, a decimal this client's own
  * AvDecimal.
  * Arrays and plain objects are copied with their members revived; any other
- * value is returned as it is. Give it to TanStack Query as \`deserializeData\`,
- * or call it on an SWR \`fallback\`.
+ * value is returned as it is. An \`AvDehydrated<T>\` revives as the \`T\`: call it
+ * on a prop of that type, such as an SWR \`fallback\`, and pass on what it
+ * returns, never the dehydrated value itself (SWR's \`fallback\` is typed
+ * \`any\`, so the type cannot catch it). Give it to TanStack Query as
+ * \`deserializeData\`.
  *
  * @throws TypeError when a tagged value is not one avDehydrate writes.
  */
+export function avHydrate<T>(dehydrated: AvDehydrated<T>): T;
+/** For a caller that cannot name the data's type: TanStack Query's \`deserializeData\`. */
+export function avHydrate(dehydrated: unknown): unknown;
 export function avHydrate(dehydrated: unknown): unknown {
 	if (Array.isArray(dehydrated)) {
 		return dehydrated.map((member: unknown) => avHydrate(member));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aventara/build",
-  "version": "1.0.0-rc.13",
+  "version": "1.0.0-rc.14",
   "license": "SEE LICENSE IN LICENSE",
   "description": "Compiles an Aventara application's Contracts at build time, for serverless and edge cold starts.",
   "type": "module",
@@ -16,18 +16,18 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@aventara/client": "1.0.0-rc.13",
+    "@aventara/client": "1.0.0-rc.14",
     "jiti": "2.7.0"
   },
   "peerDependencies": {
-    "@aventara/core": "1.0.0-rc.13",
+    "@aventara/core": "1.0.0-rc.14",
     "typescript": ">=5.7.0 <7"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@aventara/core": "1.0.0-rc.13",
+    "@aventara/core": "1.0.0-rc.14",
     "@types/node": "24.10.1",
     "typescript": "^5.9.2"
   },