@valbuild/core 0.121.0 → 0.125.0

package/dist/declarations/src/source/externalRef.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The reference stored for a file whose bytes live behind an external adapter.
+ *
+ * Deliberately the same shape of idea as a remote ref (`remote/splitRemoteRef`):
+ * a URL-ish string that **ends with the file's virtual path**, so the file's
+ * logical identity survives wherever its bytes happen to be.
+ *
+ *     /api/val/external/documents/f/{fileHash}/p/public/val/documents/report_a1b2c.pdf
+ *      \__________________________/ \________/   \_______________________________/
+ *              route + label          content        the path a LOCAL file
+ *                                     address        would have had
+ *
+ * Three things follow from that shape, and each is load-bearing:
+ *
+ * - **`media.ts` needs no change.** `isRemote` is `!path.startsWith("/public")`,
+ *   and this does not, so `Internal.mediaUrl` returns the ref as-is and Val's
+ *   route serves it. The media rule that has been got wrong repeatedly is left
+ *   exactly alone.
+ * - **Moving between storage modes is mechanical.** External → local reads the
+ *   `public/…` suffix back out, fetches the bytes and writes them there; local →
+ *   external uploads the file already at that path. Nothing is renamed.
+ * - **The filename is Val's, not the adapter's**, produced by the same
+ *   `createFilename` a local or remote file uses — so the same bytes get the
+ *   same name under all three storage modes.
+ */
+export type ExternalFileRefParts = {
+    /** The `.external(label)` of the record the file belongs to. */
+    label: string;
+    /** SHA-256 of the bytes. Content-addressed, so a retried publish re-uses. */
+    fileHash: string;
+    /** The virtual path, WITHOUT a leading slash: `public/val/...`. */
+    filePath: `public/${string}`;
+};
+export declare function createExternalFileRef({ label, fileHash, filePath, }: {
+    label: string;
+    fileHash: string;
+    /** Accepts the path as it is written in a module: `/public/val/...`. */
+    filePath: string;
+}): string;
+export declare function splitExternalFileRef(ref: string): ({
+    status: "success";
+} & ExternalFileRefParts) | {
+    status: "error";
+    error: string;
+};
+export declare function isExternalFileRef(ref: string): boolean;

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

@@ -1,8 +1,9 @@
+import { ExternalRecordSrc } from "./external.js";
 import { JsonSource } from "./json.js";
 import { MediaSource } from "./media.js";
 import { RichTextOptions, RichTextSource } from "./richtext.js";
 import { SettingsSource } from "./settings.js";
-export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | SettingsSource | RichTextSource<RichTextOptions>;
+export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<RichTextOptions>;
 export type SourceObject = {
     [key in string]: Source;
 } & {
@@ -22,7 +23,7 @@ export type SourceObject = {
 export type SourceArray = readonly Source[];
 export type SourcePrimitive = string | number | boolean | null;
 export declare const VAL_EXTENSION: "_type";
-export declare function getValExtension(source: Source): false | "" | 0 | "json" | null | undefined;
+export declare function getValExtension(source: Source): false | "" | 0 | "json" | "external" | null | undefined;
 /**
  * A phantom type parameter is one that doesn't show up at runtime, but is checked statically (and only) at compile time.
  *