@veryfront/ext-content-mdx 0.1.1185 → 0.1.1188

package/esm/src/platform/adapters/bounded-file-read.js

@@ -0,0 +1,185 @@
+const apply = Reflect.apply;
+const arrayPush = Array.prototype.push;
+const minimum = Math.min;
+const numberIsSafeInteger = Number.isSafeInteger;
+const NativeUint8Array = Uint8Array;
+const typedArrayPrototype = Object.getPrototypeOf(NativeUint8Array.prototype);
+const typedArrayByteLengthGetterCandidate = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")?.get;
+const typedArrayBufferGetterCandidate = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")?.get;
+const typedArrayByteOffsetGetterCandidate = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")?.get;
+const setBytes = NativeUint8Array.prototype.set;
+if (typeof typedArrayByteLengthGetterCandidate !== "function" ||
+    typeof typedArrayBufferGetterCandidate !== "function" ||
+    typeof typedArrayByteOffsetGetterCandidate !== "function") {
+    throw new TypeError("Required Uint8Array intrinsics are unavailable");
+}
+const typedArrayByteLengthGetter = typedArrayByteLengthGetterCandidate;
+const typedArrayBufferGetter = typedArrayBufferGetterCandidate;
+const typedArrayByteOffsetGetter = typedArrayByteOffsetGetterCandidate;
+function byteLengthOf(value) {
+    const byteLength = apply(typedArrayByteLengthGetter, value, []);
+    if (!numberIsSafeInteger(byteLength) || byteLength < 0) {
+        throw new TypeError("Filesystem read buffer has an invalid byte length");
+    }
+    return byteLength;
+}
+function allocateBytes(byteLength) {
+    const bytes = new NativeUint8Array(byteLength);
+    if (byteLengthOf(bytes) !== byteLength) {
+        throw new TypeError("Filesystem byte buffer allocation returned an invalid size");
+    }
+    return bytes;
+}
+function viewBytes(value, start, byteLength) {
+    const sourceByteLength = byteLengthOf(value);
+    if (!numberIsSafeInteger(start) || start < 0 ||
+        !numberIsSafeInteger(byteLength) || byteLength < 0 ||
+        start > sourceByteLength - byteLength) {
+        throw new RangeError("Filesystem byte view is outside its source buffer");
+    }
+    const buffer = apply(typedArrayBufferGetter, value, []);
+    const byteOffset = apply(typedArrayByteOffsetGetter, value, []);
+    const view = new NativeUint8Array(buffer, byteOffset + start, byteLength);
+    if (byteLengthOf(view) !== byteLength) {
+        throw new TypeError("Filesystem byte view allocation returned an invalid size");
+    }
+    return view;
+}
+// Keep a large caller-supplied limit from becoming an equally large eager
+// allocation when the source is small. The aggregate returned data remains
+// bounded by the caller's limit.
+const BOUNDED_FILE_READ_CHUNK_BYTES = 64 * 1024;
+/**
+ * Run one operation against one opened file handle, then close it exactly once.
+ *
+ * When the operation and cleanup both fail, the aggregate retains the primary
+ * operation failure first and the cleanup failure second.
+ */
+export async function withFileHandle(openHandle, operation, aggregateFailureMessage) {
+    const handle = await openHandle();
+    let result;
+    let primaryFailure;
+    let primaryFailed = false;
+    try {
+        result = await operation(handle);
+    }
+    catch (error) {
+        primaryFailed = true;
+        primaryFailure = error;
+    }
+    try {
+        await handle.close();
+    }
+    catch (cleanupFailure) {
+        if (primaryFailed) {
+            throw new AggregateError([primaryFailure, cleanupFailure], aggregateFailureMessage);
+        }
+        throw cleanupFailure;
+    }
+    if (primaryFailed)
+        throw primaryFailure;
+    return result;
+}
+export function requireBoundedFileReadLimit(byteLimit) {
+    if (!numberIsSafeInteger(byteLimit) || byteLimit <= 0) {
+        throw new RangeError("Filesystem byteLimit must be a positive safe integer");
+    }
+    return byteLimit;
+}
+/**
+ * Read at most `byteLimit` bytes without first materializing the whole file.
+ *
+ * A full-length result is intentionally ambiguous: callers that need to
+ * distinguish an exact-size file from an oversized file request their accepted
+ * maximum plus one byte.
+ */
+export async function readBoundedFilePrefix(openHandle, byteLimit) {
+    const boundedLimit = requireBoundedFileReadLimit(byteLimit);
+    return await withFileHandle(openHandle, (handle) => readBoundedFileHandlePrefix(handle, boundedLimit), "Filesystem read and handle cleanup both failed");
+}
+/**
+ * Read the complete file only when it fits within `byteLimit`.
+ *
+ * Unlike a prefix read, reaching the limit triggers one additional EOF probe.
+ * The probe reuses the final byte of the accepted buffer, so the helper never
+ * retains more than `byteLimit` bytes from the source.
+ */
+export async function readFileWithinLimit(openHandle, byteLimit) {
+    const boundedLimit = requireBoundedFileReadLimit(byteLimit);
+    return await withFileHandle(openHandle, (handle) => readFileHandleWithinLimit(handle, boundedLimit), "Filesystem read and handle cleanup both failed");
+}
+/** Read a bounded prefix while leaving ownership of the open handle to the caller. */
+export async function readBoundedFileHandlePrefix(reader, byteLimit) {
+    const boundedLimit = requireBoundedFileReadLimit(byteLimit);
+    const chunks = [];
+    let byteLength = 0;
+    let reachedEnd = false;
+    while (byteLength < boundedLimit) {
+        const chunk = allocateBytes(minimum(BOUNDED_FILE_READ_CHUNK_BYTES, boundedLimit - byteLength));
+        let chunkLength = 0;
+        const chunkByteLength = byteLengthOf(chunk);
+        while (chunkLength < chunkByteLength) {
+            const remaining = viewBytes(chunk, chunkLength, chunkByteLength - chunkLength);
+            const bytesRead = await reader.read(remaining);
+            if (bytesRead === null || bytesRead === 0) {
+                reachedEnd = true;
+                break;
+            }
+            if (!numberIsSafeInteger(bytesRead) ||
+                bytesRead < 0 ||
+                bytesRead > byteLengthOf(remaining)) {
+                throw new TypeError("Filesystem read returned an invalid byte count");
+            }
+            chunkLength += bytesRead;
+            byteLength += bytesRead;
+        }
+        if (chunkLength > 0) {
+            // Copy a short final chunk so a tiny result does not retain the entire
+            // fixed-size read buffer.
+            if (chunkLength === chunkByteLength) {
+                apply(arrayPush, chunks, [chunk]);
+            }
+            else {
+                const shortChunk = allocateBytes(chunkLength);
+                apply(setBytes, shortChunk, [viewBytes(chunk, 0, chunkLength)]);
+                apply(arrayPush, chunks, [shortChunk]);
+            }
+        }
+        if (reachedEnd)
+            break;
+    }
+    if (chunks.length === 0)
+        return allocateBytes(0);
+    if (chunks.length === 1)
+        return chunks[0];
+    const bytes = allocateBytes(byteLength);
+    let offset = 0;
+    for (let index = 0; index < chunks.length; index++) {
+        const chunk = chunks[index];
+        apply(setBytes, bytes, [chunk, offset]);
+        offset += byteLengthOf(chunk);
+    }
+    return bytes;
+}
+/** Read a complete bounded file while leaving ownership of the handle to the caller. */
+export async function readFileHandleWithinLimit(reader, byteLimit) {
+    const boundedLimit = requireBoundedFileReadLimit(byteLimit);
+    const bytes = await readBoundedFileHandlePrefix(reader, boundedLimit);
+    if (byteLengthOf(bytes) < boundedLimit)
+        return bytes;
+    // Reuse the final accepted byte as the EOF probe instead of allocating or
+    // retaining a maximum-plus-one buffer. Restore it when the file ends exactly
+    // at the limit; on overflow the result is discarded.
+    const finalIndex = boundedLimit - 1;
+    const acceptedFinalByte = bytes[finalIndex];
+    const probe = viewBytes(bytes, finalIndex, 1);
+    const bytesRead = await reader.read(probe);
+    if (bytesRead === null || bytesRead === 0) {
+        bytes[finalIndex] = acceptedFinalByte;
+        return bytes;
+    }
+    if (!numberIsSafeInteger(bytesRead) || bytesRead < 0 || bytesRead > byteLengthOf(probe)) {
+        throw new TypeError("Filesystem read returned an invalid byte count");
+    }
+    throw new RangeError(`File exceeds byte limit of ${boundedLimit} ${boundedLimit === 1 ? "byte" : "bytes"}`);
+}

package/esm/src/platform/adapters/file-snapshot-error.d.ts

@@ -0,0 +1,8 @@
+/** Error raised when a file changes while a stable snapshot is being read. */
+export declare class FileSnapshotChangedError extends Error {
+    readonly name = "FileSnapshotChangedError";
+    constructor(message?: string);
+}
+/** Return whether a value is a framework-created file snapshot change error. */
+export declare function isFileSnapshotChangedError(value: unknown): value is FileSnapshotChangedError;
+//# sourceMappingURL=file-snapshot-error.d.ts.map

package/esm/src/platform/adapters/file-snapshot-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-snapshot-error.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/adapters/file-snapshot-error.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,SAAkB,IAAI,8BAA8B;gBAExC,OAAO,SAA0C;CAI9D;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,wBAAwB,CAEnC"}

package/esm/src/platform/adapters/file-snapshot-error.js

@@ -0,0 +1,13 @@
+const changedErrors = new WeakSet();
+/** Error raised when a file changes while a stable snapshot is being read. */
+export class FileSnapshotChangedError extends Error {
+    name = "FileSnapshotChangedError";
+    constructor(message = "File snapshot changed during the read") {
+        super(message);
+        changedErrors.add(this);
+    }
+}
+/** Return whether a value is a framework-created file snapshot change error. */
+export function isFileSnapshotChangedError(value) {
+    return typeof value === "object" && value !== null && changedErrors.has(value);
+}

package/esm/src/platform/adapters/file-system-capabilities.d.ts

@@ -0,0 +1,74 @@
+type ByteReader = (path: string) => Promise<Uint8Array>;
+type BoundedByteReader = (path: string, byteLimit: number) => Promise<Uint8Array>;
+type ByteWriter = (path: string, content: Uint8Array) => Promise<void>;
+export interface CapturedWholeFileReader {
+    readonly maximumBytes: number;
+    readonly read: ByteReader;
+}
+export interface CapturedFileSystemCapabilities {
+    readonly readFileBytes?: ByteReader;
+    readonly readFileBytesBounded?: BoundedByteReader;
+    readonly readFileBytesWithinLimit?: BoundedByteReader;
+    readonly writeFileBytes?: ByteWriter;
+    readonly wholeFileReader?: CapturedWholeFileReader;
+}
+/** Compatibility view used by existing filesystem wrappers and adapters. */
+export interface CapturedByteReaders {
+    readonly unbounded?: ByteReader;
+    readonly whole?: CapturedWholeFileReader;
+    readonly prefix?: BoundedByteReader;
+    readonly exact?: BoundedByteReader;
+}
+export interface CapturedSnapshotReader {
+    read(path: string, containmentRoot: string, byteLimit: number): Promise<Uint8Array>;
+}
+export interface CapturedExclusiveCreator {
+    create(path: string, content: Uint8Array): Promise<void>;
+}
+export interface CapturedStaticReaders {
+    snapshot?: CapturedSnapshotReader;
+    virtual?: {
+        generation(): Promise<number>;
+        exact?: (path: string, byteLimit: number) => Promise<Uint8Array>;
+        whole?: {
+            maximumBytes: number;
+            read(path: string): Promise<Uint8Array>;
+        };
+    };
+}
+/**
+ * Admit an untrusted byte result before copying it into an immutable-size,
+ * tightly allocated ArrayBuffer. The maximum is checked from the intrinsic
+ * Uint8Array byte length before allocating the defensive copy.
+ */
+export declare function copyFixedUint8ArrayWithinLimit(value: unknown, maximumBytes: number, label: string): Uint8Array;
+/**
+ * Extract the ArrayBuffer from an admitted tight fixed Uint8Array without
+ * consulting mutable global constructors or configurable typed-array getters.
+ */
+export declare function getFixedUint8ArrayBuffer(value: unknown, label: string): ArrayBuffer;
+/** Read the intrinsic byte length only after verifying a tight fixed buffer. */
+export declare function getFixedUint8ArrayByteLength(value: unknown, label: string): number;
+/**
+ * Preserve the broad legacy capture temporarily for its scheduled consumers.
+ * Bounded text passes the narrow purpose so writer and prefix fields are never
+ * inspected.
+ */
+export declare function captureFileSystemCapabilities(value: unknown, label?: string, purpose?: "legacy" | "bounded-text" | "byte-read"): CapturedFileSystemCapabilities;
+/**
+ * Capture the established byte-reader surface while defensively admitting
+ * every result. New purpose-specific code should prefer the narrower capture
+ * functions above.
+ */
+export declare function captureByteReadCapabilities(value: unknown, label?: string): CapturedByteReaders;
+/**
+ * Capture legacy byte capabilities after genuine snapshot authority has been
+ * proven independently. Malformed optional fields are omitted one at a time;
+ * unsafe object or prototype provenance still rejects the adapter.
+ */
+export declare function captureLegacyFileSystemCapabilitiesForSnapshot(value: unknown, label?: string): CapturedFileSystemCapabilities;
+export declare function captureSnapshotReadCapability(value: unknown, label?: string, allowExplicitUndefined?: boolean): CapturedSnapshotReader | undefined;
+export declare function captureExclusiveCreateCapability(value: unknown, label?: string): CapturedExclusiveCreator | undefined;
+export declare function captureStaticReadCapabilities(value: unknown, label?: string): CapturedStaticReaders;
+export {};
+//# sourceMappingURL=file-system-capabilities.d.ts.map

package/esm/src/platform/adapters/file-system-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-system-capabilities.d.ts","sourceRoot":"","sources":["../../../../src/src/platform/adapters/file-system-capabilities.ts"],"names":[],"mappings":"AA8EA,KAAK,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AACxD,KAAK,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;AAMlF,KAAK,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAGvE,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,UAAU,CAAC;IACpC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,iBAAiB,CAAC;IAClD,QAAQ,CAAC,wBAAwB,CAAC,EAAE,iBAAiB,CAAC;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,uBAAuB,CAAC;CACpD;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;IAClC,OAAO,CAAC,EAAE;QACR,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9B,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;QACjE,KAAK,CAAC,EAAE;YAAE,YAAY,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;SAAE,CAAC;KAC3E,CAAC;CACH;AAmJD;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GACZ,UAAU,CAyDZ;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAsBnF;AAED,gFAAgF;AAChF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOlF;AAmED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,KAAK,SAAe,EACpB,OAAO,GAAE,QAAQ,GAAG,cAAc,GAAG,WAAsB,GAC1D,8BAA8B,CAyDhC;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,KAAK,SAAe,GACnB,mBAAmB,CAqDrB;AAeD;;;;GAIG;AACH,wBAAgB,8CAA8C,CAC5D,KAAK,EAAE,OAAO,EACd,KAAK,SAAe,GACnB,8BAA8B,CAkDhC;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,KAAK,SAAe,EACpB,sBAAsB,UAAQ,GAC7B,sBAAsB,GAAG,SAAS,CAsBpC;AAED,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,OAAO,EACd,KAAK,SAAe,GACnB,wBAAwB,GAAG,SAAS,CAiBtC;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,KAAK,SAAe,GACnB,qBAAqB,CA4DvB"}