@valbuild/server 0.103.2 → 0.105.1

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

@@ -3,7 +3,7 @@ import { result } from "@valbuild/core/fp";
 import { JSONValue, ParentRef, Patch, PatchError } from "@valbuild/core/patch";
 import { ValSyntaxError, ValSyntaxErrorTree } from "./patch/ts/syntax.js";
 import { ParentPatchId } from "@valbuild/core";
-import type { ReifiedRender } from "@valbuild/core";
+import type { ReifiedPreview } from "@valbuild/core";
 import { ValCommit, ValDeployment } from "@valbuild/shared/internal";
 export type BaseSha = string & {
     readonly _tag: unique symbol;
@@ -57,6 +57,40 @@ export declare abstract class ValOps {
     /** The sha256 / hash of schema + config - if this changes users needs to reload */
     private schemaSha;
     private modulesErrors;
+    /**
+     * What the SHAs above are a fold over, so they can be recomputed.
+     *
+     * See {@link promoteCommittedSources}: the one thing that changes sources
+     * without re-evaluating the modules is a save, and it has to be able to move
+     * the SHAs with them.
+     */
+    private shaEntries;
+    /**
+     * The extraction's OWN module errors, which are what the fold was given.
+     *
+     * Not the same list as {@link modulesErrors}: that one has the nested
+     * `.jsonValues()` errors concatenated on, and those were never part of the
+     * hash. Re-folding with the wrong list changes the base SHA for no reason.
+     */
+    private shaModuleErrors;
+    /**
+     * What a save has told us each `.jsonValues()` entry now holds.
+     *
+     * The entry twin of {@link sources}, and it has to be separate because an
+     * entry's content is not IN the source: the source holds a marker, and
+     * {@link getJsonEntries} resolves it by awaiting the marker's own `import()`.
+     * That resolves from the module registry, so after `/save` rewrites a
+     * `*.val.json` the thunk keeps answering with the content from before — and
+     * 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.
+     *
+     * 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,
+     * holding only the latest content per key.
+     */
+    private adoptedJsonEntries;
     constructor(valModules: ValModules, options?: ValOpsOptions | undefined);
     /**
      * Get the status from Val
@@ -111,6 +145,67 @@ export declare abstract class ValOps {
         networkError?: boolean;
     }>;
     private initSources;
+    /**
+     * These patches are on disk now: adopt what they produced as the committed
+     * sources.
+     *
+     * The entry point for the mechanism {@link promoteCommittedSources} describes,
+     * and the only one — a caller hands over the analysis it just committed and
+     * this works out the rest, so the rule about which sources are adopted lives
+     * in one place rather than at each save site.
+     *
+     * A module whose patches could not be applied cleanly is left alone. `/save`
+     * refuses the whole commit before reaching here if `prepare` found errors, so
+     * this cannot normally fire — but adopting a partially patched source would
+     * put content in the memo that is not what was written, which is worse than
+     * being stale.
+     */
+    adoptCommittedSources(analysis: PatchAnalysis & OrderedPatches, preparedCommit: Pick<PreparedCommit, "patchedJsonEntries">): Promise<void>;
+    /**
+     * Adopt sources that have just been written to disk, and move the SHAs with
+     * them.
+     *
+     * ## Why this exists rather than an invalidation
+     *
+     * The obvious thing — throw the memo away after a save so the next read
+     * re-extracts — does not work, and quietly. `extractValModules` gets a
+     * module's content by awaiting its `def`, which is the app's own `import()`:
+     * that resolves from the MODULE REGISTRY, not from the file on disk. Right
+     * after `/save` rewrites a `.val.ts`, the registry still holds the module as
+     * it was evaluated before, so a re-extraction returns the pre-save content and
+     * stores it as fresh. What actually replaces it is the host rebuilding its
+     * module graph and constructing a new `ValOps` — which happens on its own
+     * schedule, and until it does, every read is stale.
+     *
+     * Stale reads here are not abstract: `getJsonEntry` resolves a
+     * `.jsonValues()` entry from the committed source and then replays pending
+     * patches over it, so once a publish has removed the patches, a page rendering
+     * draft content gets the committed value — the one this memo is holding from
+     * before the publish.
+     *
+     * So the save tells us instead. It has just computed what the new committed
+     * sources are, and that answer does not depend on anything being
+     * re-evaluated.
+     *
+     * ## And the SHAs move
+     *
+     * Deliberately, and this is the part with consequences. `baseSha` and
+     * `sourcesSha` identify the sources being served; leaving them still while the
+     * sources move would put a value other code compares against into
+     * disagreement with what it describes. Moving them means a `fs`-mode base SHA
+     * changes within a server's lifetime for the first time, which is a signal the
+     * studio already knows how to read: `PatchStore.reconcileVanished` uses a
+     * moved base to tell "these patches were published" from "these patches were
+     * discarded", and takes them out of the chain without reverting the fields —
+     * which is what a second tab watching a publish needs and could not get
+     * before.
+     *
+     * A module the fold does not know is ignored rather than appended: the fold's
+     * order is `val.modules`, and a path that is not in it has no position, so
+     * there is no honest answer for where its hash would go. It also cannot happen
+     * — a save only ever writes modules it read from here.
+     */
+    protected promoteCommittedSources(patched: Sources): void;
     init(): Promise<void>;
     getBaseSources(): Promise<Sources>;
     /**
@@ -198,16 +293,19 @@ export declare abstract class ValOps {
     getSchemaSha(): Promise<SchemaSha>;
     analyzePatches(sortedPatches: OrderedPatches["patches"], commits?: ValCommit[], currentCommitSha?: CommitSha): PatchAnalysis;
     /**
-     * Reifies each module's render from its schema INSTANCE.
+     * Reifies each module's previews from its schema INSTANCE.
      *
-     * Kept even though the Studio also computes renders client-side: `select` is a
-     * user function that lives on the instance and is not part of the serialized
+     * Kept even though the Studio also computes previews client-side: a preview is
+     * a user function that lives on the instance and is not part of the serialized
      * schema, so a host app that does not render `<ValModulesClient>` has no
-     * instances in the browser and would otherwise get no renders at all. See
+     * instances in the browser and would otherwise get no previews at all. See
      * #470.
+     *
+     * A string's `render` needs none of this — it is static config that travels
+     * with the serialized schema.
      */
-    getRenders(schemas: Schemas, sources: Sources): Promise<{
-        renders: Record<ModuleFilePath, ReifiedRender | null>;
+    getPreviews(schemas: Schemas, sources: Sources): Promise<{
+        previews: Record<ModuleFilePath, ReifiedPreview | null>;
     }>;
     getSources(analysis?: PatchAnalysis & OrderedPatches): Promise<{
         sources: Sources;
@@ -365,6 +463,23 @@ export type PreparedCommit = {
      * A null value signals that the file at that path should be deleted.
      */
     patchedSourceFiles: Record<string, string | null>;
+    /**
+     * The committed content of every `.jsonValues()` entry this commit changed,
+     * per module and entry key. `null` means the entry was deleted.
+     *
+     * Separate from {@link patchedSourceFiles} rather than folded into it, because
+     * that map is keyed by FILE PATH and a reader of an entry has a module and a
+     * key. A marker does not carry its path at read time, so the two are not
+     * interchangeable — see `jsonEntryFiles.ts`.
+     *
+     * Here for {@link ValOps.adoptCommittedSources}: an entry's committed content
+     * is resolved through the marker's own `import()`, which caches, so a save is
+     * the only thing that can tell the server what the entry now holds.
+     *
+     * Only modules whose patches applied cleanly appear; a module that errored
+     * contributes nothing, and `/save` refuses the commit anyway.
+     */
+    patchedJsonEntries: Record<ModuleFilePath, Record<string, JSONValue | null>>;
     /**
      * Previous source files that were patched
      */

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

@@ -120,6 +120,15 @@ export declare class ValOpsFS extends ValOps {
         patchId: PatchId;
         filePath: string;
     }>>;
+    /**
+     * Which of the two places a patch's file can be, if either.
+     *
+     * The bytes are in the store once the patch's record is, and in the staging
+     * area before that — see `uploadsDir`. Every reader has to accept both, and
+     * they decide it here rather than each on its own, so two readers of the same
+     * file cannot disagree about whether it exists.
+     */
+    private wherePatchFileIs;
     protected getBase64EncodedBinaryFileMetadataFromPatch<T extends BinaryFileType>(filePath: string, type: T, patchId: PatchId): Promise<OpsMetadata<T>>;
     getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId): Promise<Buffer | null>;
     deletePatches(patchIds: PatchId[]): Promise<{

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

@@ -5,4 +5,4 @@ import { ValidationError } from "@valbuild/core";
  * There is no schema in hand here — a `ValidationError` carries only the value
  * it flagged — so the shape is all there is to go on.
  */
-export declare function getValidationErrorFileRef(validationError: ValidationError): string | null;
+export declare function getValidationErrorFileRef(validationError: ValidationError): any;

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

@@ -1,4 +1,4 @@
-import { ModuleFilePath, PatchId } from "@valbuild/core";
+import { PatchId } from "@valbuild/core";
 import { z } from "zod";
 import type { AuthorId, BaseSha } from "./ValOps.js";
 import { PatchLogEntry, PatchLogProblem } from "./patchLog.js";
@@ -32,14 +32,14 @@ export declare const FSPatch: z.ZodObject<{
     patch: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         op: z.ZodLiteral<"add">;
         path: z.ZodArray<z.ZodString>;
-        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"remove">;
         path: z.ZodTuple<[z.ZodString], z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"replace">;
         path: z.ZodArray<z.ZodString>;
-        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"move">;
         from: z.ZodTuple<[z.ZodString], z.ZodString>;
@@ -51,15 +51,15 @@ export declare const FSPatch: z.ZodObject<{
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"test">;
         path: z.ZodArray<z.ZodString>;
-        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
     }, z.core.$strict>, z.ZodObject<{
         op: z.ZodLiteral<"file">;
         path: z.ZodArray<z.ZodString>;
         filePath: z.ZodString;
-        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+        value: z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>;
         remote: z.ZodBoolean;
         nestedFilePath: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        metadata: z.ZodOptional<z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>>;
+        metadata: z.ZodOptional<z.ZodType<JSONValueT, unknown, z.core.$ZodTypeInternals<JSONValueT, unknown>>>;
     }, z.core.$strict>], "op">>;
     patchId: z.ZodString;
     baseSha: z.ZodString & z.ZodType<BaseSha, string, z.core.$ZodTypeInternals<BaseSha, string>>;
@@ -147,8 +147,53 @@ export declare function patchRepairLogFile(patchesDir: string): string;
 export declare function patchDir(patchesDir: string, patchId: PatchId): string;
 export declare function patchRecordFile(patchesDir: string, patchId: PatchId): string;
 export declare function patchBaseFile(patchesDir: string, patchId: PatchId): string;
+/**
+ * Where a patch's uploaded bytes wait for the record that will reference them.
+ *
+ * ## Why they cannot simply be written into the patch directory
+ *
+ * A patch that carries a file is written in TWO requests, and the bytes go
+ * first: the record's `file` op holds only a sha, so a record written before its
+ * bytes would point at nothing. Uploading straight into `<patchId>/files/` left
+ * the directory holding files and no `patch.json` for the length of a round
+ * trip — which is neither of the two shapes this store allows, so
+ * {@link readPatchStore} read it as a patch whose contents were lost and repair
+ * removed it, bytes and all.
+ *
+ * And that window is not passive: writing into the patches directory is exactly
+ * what ends `getStat`'s long poll, so the upload summoned the read that
+ * destroyed it. Replacing an image worked only when the two requests happened to
+ * land close enough together.
+ *
+ * So the bytes are not in the store until they belong to something.
+ * {@link appendPatch} moves them in after writing the record, under the lock, so
+ * no reader ever sees a half-built patch directory — and the invariant that a
+ * directory either holds a usable record or is named by the log holds again,
+ * with nothing to tolerate and no ambiguous state to classify.
+ *
+ * A SIBLING of the patches directory, for two reasons: nothing that reads the
+ * store lists it, and it is on the same filesystem, so moving into place is a
+ * rename rather than a copy.
+ */
+export declare function uploadsDir(patchesDir: string): string;
+/** Where one patch's uploads wait. See {@link uploadsDir}. */
+export declare function patchUploadDir(patchesDir: string, patchId: PatchId): string;
 export declare function patchBinaryFile(patchesDir: string, patchId: PatchId, filePath: string): string;
 export declare function patchBinaryFileMetadata(patchesDir: string, patchId: PatchId, filePath: string): string;
+/** The staged twin of {@link patchBinaryFile}. */
+export declare function stagedPatchBinaryFile(patchesDir: string, patchId: PatchId, filePath: string): string;
+/** The staged twin of {@link patchBinaryFileMetadata}. */
+export declare function stagedPatchBinaryFileMetadata(patchesDir: string, patchId: PatchId, filePath: string): string;
+/** Drop a patch's staging directory, whatever is left of it. */
+export declare function removeStagedUploads(patchesDir: string, patchId: PatchId): void;
+/**
+ * Drop staged uploads whose patch never arrived.
+ *
+ * A client that dies between the upload and the `PUT` leaves its bytes here.
+ * Nothing references them — no record points at them and the log never named
+ * them — so they are removed without a word.
+ */
+export declare function sweepStaleUploads(patchesDir: string, now?: number): void;
 /**
  * Read the whole store: the order, the records, and everything wrong with it.
  *