@valbuild/server 0.144.0 → 0.144.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @valbuild/server
 
+## 0.144.2
+
+### Patch Changes
+
+- [#832](https://github.com/valbuild/val/pull/832) [`ab0ea20`](https://github.com/valbuild/val/commit/ab0ea2046e3872c4955f34b363881f76d48d1b1e) Thanks [@freekh](https://github.com/freekh)! - A site served by Val's platform can now be given its content separately from its build. When the platform hands a TanStack app a content version (`VAL_CONTENT`) that differs from what the build bundles, Val renders that content, in the Studio and in draft mode too. It reads it the way it already reads a proposal's saved content.
+
+  Nothing changes for an app that is not given one, and nothing hands one over yet. This is the reading side of publishing content without rebuilding the site.
+
+  A version too large for one environment variable can name others under `refs` (`"env://VAL_CONTENT_1"`), each holding one module's Source or one file's text. Only `refs` is resolved, never a string inside your content, and only variables named `VAL_CONTENT_<n>` are read.
+
+  At a proposal's address, a proposal's saved content is shown over the content version the site serves, so modules the proposal did not change show what the site shows rather than what the build bundles.
+
+  When Val's platform puts a publish live without building the site, because it changed only content, the Studio shows it being checked and going live instead of "Building".
+
+- Updated dependencies [[`ab0ea20`](https://github.com/valbuild/val/commit/ab0ea2046e3872c4955f34b363881f76d48d1b1e), [`44a5636`](https://github.com/valbuild/val/commit/44a5636955e005a40f2e6c8544e5cf4378fd0fdf)]:
+  - @valbuild/shared@0.144.2
+  - @valbuild/ui@0.144.2
+
+## 0.144.1
+
+### Patch Changes
+
+- [#824](https://github.com/valbuild/val/pull/824) [`a641bb0`](https://github.com/valbuild/val/commit/a641bb0286756339252c53e9230d766c23fcccc6) Thanks [@freekh](https://github.com/freekh)! - `.jsonValues()` entries saved in a proposal now show at the proposal's address. Before, the page kept showing the entry as it was when the site was last built, and the Studio there showed every entry of a saved `.jsonValues()` module as empty.
+
 ## 0.144.0
 
 ### Patch Changes

package/dist/declarations/src/ValOps.d.ts

@@ -51,6 +51,21 @@ export type ValOpsOptions = {
      * the next save's prepare -- starts from it, and the SHAs describe it.
      */
     snapshotSources?: Sources;
+    /**
+     * Source the SITE serves over what the modules evaluate to, beneath
+     * {@link snapshotSources}: a content version (`ValContentVersion` in
+     * `./proposal`), the content published since the build. Applied the same
+     * way, and what a proposal's saves are compared against
+     * ({@link ValOps.siteSourcesUnderSnapshot}) -- the site, not the bundle.
+     */
+    siteSnapshotSources?: Sources;
+    /**
+     * The `.jsonValues()` entries the same snapshot saved, by module and key:
+     * their content is in their own files, not in {@link snapshotSources}, which
+     * holds markers. The baseline those entries are read from, as a save in
+     * this instance would leave them (`proposalJsonEntries` in `./proposal`).
+     */
+    snapshotJsonEntries?: Map<ModuleFilePath, Map<string, JSONValue>>;
 };
 export declare abstract class ValOps {
     private readonly valModules;
@@ -90,6 +105,13 @@ export declare abstract class ValOps {
      * {@link siteSourcesUnderSnapshot}, and only where there is a snapshot.
      */
     private siteSourcesBeforeSnapshot;
+    /**
+     * The same modules as the bundle evaluated them, imports and all: where a
+     * `.jsonValues()` entry the snapshot did not save is read from. Not
+     * {@link siteSourcesBeforeSnapshot}, whose markers may have come as JSON
+     * from a content version, with no import behind them.
+     */
+    private bundleSourcesBeforeSnapshot;
     /**
      * What a save has told us each `.jsonValues()` entry now holds.
      *
@@ -101,7 +123,9 @@ export declare abstract class ValOps {
      * unlike a module source there is nothing to re-extract, because the memo was
      * never holding the content in the first place.
      *
-     * `null` for an entry the commit deleted.
+     * `deleted` for an entry the commit deleted: tagged, not `null`, because an
+     * entry's content may itself be JSON `null` (a nullable item), and a saved
+     * `null` read back as "deleted" would report the entry missing.
      *
      * Never cleared: it describes what is on disk. A host rebuild makes a new
      * instance, which is the right reset. Bounded by the project's entry count,

package/dist/declarations/src/ValOpsHttp.d.ts

@@ -1,4 +1,4 @@
-import { type ValProposal } from "./proposal.js";
+import { type ValContentVersion, type ValProposal } from "./proposal.js";
 import { type PatchId, type ModuleFilePath, ValModules } from "@valbuild/core";
 import type { Patch as PatchT, ParentRef as ParentRefT } from "@valbuild/core/patch";
 import { type AuthorId, type BaseSha, BinaryFileType, type CommitSha, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, OrderedPatchesMetadata, OrderedPatches, SourcesSha, type PublishRefusal } from "./ValOps.js";
@@ -81,6 +81,8 @@ export declare class ValOpsHttp extends ValOps {
     private readonly publishBuild;
     /** See `proposal` on {@link ValApiOptions}; `null` on the site. */
     private readonly proposal;
+    /** See `contentVersion` on {@link ValApiOptions}; `null` at a proposal's address. */
+    private readonly contentVersion;
     /** Did the host hand over the running build's source? See `projectSource`. */
     embedsSource(): boolean;
     /**
@@ -153,6 +155,8 @@ export declare class ValOpsHttp extends ValOps {
         publishBuild?: string;
         /** See `proposal` on {@link ValApiOptions}. */
         proposal?: ValProposal;
+        /** See `contentVersion` on {@link ValApiOptions}. */
+        contentVersion?: ValContentVersion;
     });
     /**
      * A deployment that cannot mirror a project which expects to be mirrored.

package/dist/declarations/src/ValRouter.d.ts

@@ -8,7 +8,7 @@ type Versions = {
     };
 };
 import type { ValPatchStore } from "./ValOpsMemory.js";
-import type { ValProposal } from "./proposal.js";
+import type { ValContentVersion, ValProposal } from "./proposal.js";
 import type { CommitContext, CommitResult } from "./ValServer.js";
 export type ValApiOptions = ValServerOverrides & ValConfig & Versions;
 type ValServerOverrides = Partial<{
@@ -163,6 +163,14 @@ type ValServerOverrides = Partial<{
      * and the snapshot that replaces the bundle's Source for what it saved.
      */
     proposal?: ValProposal;
+    /**
+     * The content version the site serves, when a platform says it differs from
+     * the one this build bundles (`VAL_CONTENT`; read it with `contentFromEnv`).
+     * See {@link ValContentVersion}: its Source replaces the bundle's for what
+     * it holds, and its publish is this server's position. Ignored at a
+     * proposal's address.
+     */
+    contentVersion?: ValContentVersion;
     /**
      * The base url of Val.
      *

package/dist/declarations/src/ValServer.d.ts

@@ -1,4 +1,4 @@
-import type { ValProposal } from "./proposal.js";
+import type { ValContentVersion, ValProposal } from "./proposal.js";
 import { ValModules, PatchId, ModuleFilePath, ValConfig } from "@valbuild/core";
 import { Api, ServerOf, type PatchGroupT } from "@valbuild/shared/internal";
 import { z } from "zod";
@@ -148,6 +148,8 @@ export type ValServerConfig = ValServerOptions & ({
     publishBuild?: string;
     /** See `proposal` on {@link ValApiOptions}. */
     proposal?: ValProposal;
+    /** See `contentVersion` on {@link ValApiOptions}. */
+    contentVersion?: ValContentVersion;
     config: ValConfig;
 }
 /**

package/dist/declarations/src/index.d.ts

@@ -2,8 +2,8 @@ export { createService, Service } from "./Service.js";
 export { defineExternal, ok, err, isExternalResult, EXTERNAL_RESULT, } from "./externalRecords.js";
 export type { AdapterFor, BoundExternalRecord, ExternalAuthor, ExternalBuilder, ExternalCtx, ExternalDefinition, ExternalFile, ExternalIssue, ExternalKeyPage, ExternalRecords, ExternalResult, ExternalSearchHit, ExternalSearchPage, ExternalSort, ItemOfModule, ReadonlyRecordHasNoWrites, Returns, } from "./externalRecords.js";
 export { createValApiRouter, createValServer, safeReadGit } from "./ValRouter.js";
-export { proposalFromEnv, proposalSnapshot } from "./proposal.js";
-export type { ValProposal } from "./proposal.js";
+export { contentFromEnv, proposalFromEnv, layeredSnapshot, proposalSnapshot, proposalSnapshotForReaders, } from "./proposal.js";
+export type { ValContentVersion, ValProposal } from "./proposal.js";
 export { initHandlerOptions, createValOps } from "./valServerConfig.js";
 export { resolveRemoteFileAuth } from "./valServerConfig.js";
 export { APP_MODE_REQUIRES_REMOTE_FILES } from "./valServerConfig.js";

package/dist/declarations/src/proposal.d.ts

@@ -1,4 +1,5 @@
 import type { Json, ModuleFilePath } from "@valbuild/core";
+import type { JSONValue } from "@valbuild/core/patch";
 /**
  * A proposal this server runs at the address of: an editor-managed branch of
  * the project's content, served from its own copy of the content the
@@ -64,9 +65,89 @@ export declare function proposalFromEnv(env: {
     VAL_BRANCH?: string | undefined;
     VAL_OVERLAY?: string | undefined;
 }): ValProposal | undefined;
+/**
+ * A content version: the site's content, served by a build that bundles an
+ * older one. valbuild/home `docs/hosted-publishing.md`, step 2.
+ *
+ * The platform hands over only what differs from the bundle -- the modules
+ * whose Source changed and the Val files whose text did -- the way it hands a
+ * proposal's address its saved content, and it is read the same way: the
+ * snapshot source provider, over the bundle. What differs is the position: a
+ * version names the publish that made it (`job`, or its `commit`), and that is
+ * where this server says it sits, never at the build it runs in.
+ */
+export type ValContentVersion = {
+    /** The version's id: the hash of its manifest, as the platform stores it. */
+    id: string;
+    /** The publish job that made it, when a job did. */
+    job: string | null;
+    /** Its place in the chain: the commit that publish minted. */
+    commit: string | null;
+    /** Source, by module file path, for the modules that differ from the bundle. */
+    modules: Record<string, unknown>;
+    /** Val file text, by path, for the files that differ from the bundle. */
+    files: Record<string, string>;
+};
+/**
+ * The content version a platform hands over in its runtime env
+ * (`VAL_CONTENT`), or `undefined` when it hands over none.
+ *
+ * Throws on one it cannot read rather than serving the bundle as though it
+ * were the version: the site would show content older than what was
+ * published, and nothing would say so.
+ *
+ * A version too large for one variable names others under `refs`: a module's
+ * Source (JSON) or a file's text, each in a variable of its own --
+ * `{ "refs": { "modules": { "/a.val.ts": "env://VAL_CONTENT_1" } } }`. Flat:
+ * a referenced variable holds the value itself and is never read for further
+ * references. Only `refs` is resolved, never a string inside Source, and only
+ * `VAL_CONTENT_<n>` is ever read: Source is text editors write, and a
+ * reference resolved in there would read any variable the isolate holds,
+ * `VAL_SECRET` included, into a page. The scheme leaves room for another
+ * place to read from; one this does not know is refused, not skipped.
+ */
+export declare function contentFromEnv(env: Record<string, string | undefined>): ValContentVersion | undefined;
+/**
+ * What a server or reader renders over the bundle: a proposal's saves over the
+ * content version the site serves, either alone, or nothing.
+ *
+ * Layered rather than chosen. At a proposal's address the platform hands both
+ * when the base the proposal was opened from serves content its build does not
+ * bundle (a content-only publish), and the proposal saves only the modules it
+ * changed: choosing the proposal alone would show every other module as the
+ * build bundles it -- older than the site it was opened from.
+ */
+export declare function layeredSnapshot(proposal: Pick<ValProposal, "modules" | "files"> | undefined, contentVersion: Pick<ValContentVersion, "modules" | "files"> | undefined): Pick<ValProposal, "modules" | "files"> | undefined;
 /**
  * The proposal's saved Source, as Source: every module whose value is JSON.
  * One place, so the server and the readers that render without it agree on
  * what the snapshot holds.
  */
 export declare function proposalSnapshot(proposal: Pick<ValProposal, "modules">): Record<ModuleFilePath, Json>;
+/**
+ * The `.jsonValues()` entries the proposal saved, by module and key.
+ *
+ * An entry's content is not in its module's Source -- that holds a marker per
+ * entry -- but in the entry's own `*.val.json`, and a save writes that file:
+ * it reaches the proposal's address as saved TEXT ({@link ValProposal.files}),
+ * not as Source. So the snapshot alone shows the build's entries. This is the
+ * other half: each saved `*.val.json`, read as the entry its module names.
+ *
+ * Which entry a file is comes from the module's `.val.ts`, whose
+ * `c.json(() => import("..."))` thunks name the files -- the saved text if
+ * the save rewrote it, else the build's own (`projectSource`). An entry whose
+ * module cannot be read that way is left to the build, as before: this adds
+ * what it can find and never fails the address.
+ */
+export declare function proposalJsonEntries(proposal: Pick<ValProposal, "modules" | "files">, projectSource?: Record<string, string>): Map<ModuleFilePath, Map<string, JSONValue>>;
+/**
+ * The snapshot as a page reads it: {@link proposalSnapshot}, with each saved
+ * `.jsonValues()` entry's content in place of its marker -- the shape a draft
+ * already has, where the entries it edits hold content and the rest are
+ * markers the readers resolve from the build. See {@link proposalJsonEntries}.
+ *
+ * For the readers only. Val's own server keeps the markers
+ * ({@link proposalSnapshot}): its patching works on them, and it takes the
+ * saved entries separately.
+ */
+export declare function proposalSnapshotForReaders(proposal: Pick<ValProposal, "modules" | "files">, projectSource?: Record<string, string>): Record<ModuleFilePath, Json>;