@effect-vfs/core 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runtime-neutral virtual filesystem contracts and constructors.
+ *
+ * @since 0.1.0
+ */
+/**
+ * Virtual filesystem contracts, schemas, errors, and constructors.
+ *
+ * @category exports
+ * @since 0.1.0
+ */
+export * as VirtualFileSystem from "./VirtualFileSystem.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;GAKG;AACH,OAAO,KAAK,iBAAiB,MAAM,wBAAwB,CAAA"}

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Runtime-neutral virtual filesystem contracts and constructors.
+ *
+ * @since 0.1.0
+ */
+/**
+ * Virtual filesystem contracts, schemas, errors, and constructors.
+ *
+ * @category exports
+ * @since 0.1.0
+ */
+export * as VirtualFileSystem from "./VirtualFileSystem.js";

package/dist/internal/image.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Snapshot validation and serialization used by `VirtualFileSystem`.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { ImageError, type Snapshot } from "../Snapshot.js";
+/** @internal */
+export declare const StoredMetadata: Schema.Struct<{
+    readonly uid: Schema.Finite;
+    readonly gid: Schema.Finite;
+    readonly mode: Schema.Finite;
+    readonly atimeNs: Schema.String;
+    readonly mtimeNs: Schema.String;
+    readonly ctimeNs: Schema.String;
+    readonly birthtimeNs: Schema.String;
+}>;
+/** @internal */
+export type StoredMetadata = typeof StoredMetadata.Type;
+/** @internal */
+export declare const Record: Schema.Union<readonly [Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literal<"directory">;
+    readonly metadata: Schema.Struct<{
+        readonly uid: Schema.Finite;
+        readonly gid: Schema.Finite;
+        readonly mode: Schema.Finite;
+        readonly atimeNs: Schema.String;
+        readonly mtimeNs: Schema.String;
+        readonly ctimeNs: Schema.String;
+        readonly birthtimeNs: Schema.String;
+    }>;
+    readonly entries: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly target: Schema.String;
+    }>>;
+}>, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literal<"file">;
+    readonly metadata: Schema.Struct<{
+        readonly uid: Schema.Finite;
+        readonly gid: Schema.Finite;
+        readonly mode: Schema.Finite;
+        readonly atimeNs: Schema.String;
+        readonly mtimeNs: Schema.String;
+        readonly ctimeNs: Schema.String;
+        readonly birthtimeNs: Schema.String;
+    }>;
+    readonly data: Schema.String;
+}>, Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literal<"symlink">;
+    readonly metadata: Schema.Struct<{
+        readonly uid: Schema.Finite;
+        readonly gid: Schema.Finite;
+        readonly mode: Schema.Finite;
+        readonly atimeNs: Schema.String;
+        readonly mtimeNs: Schema.String;
+        readonly ctimeNs: Schema.String;
+        readonly birthtimeNs: Schema.String;
+    }>;
+    readonly target: Schema.String;
+}>]>;
+/** @internal */
+export type Record = typeof Record.Type;
+/** @internal */
+export declare const Document: Schema.Struct<{
+    readonly format: Schema.Literal<"effect-vfs">;
+    readonly version: Schema.Literal<1>;
+    readonly root: Schema.String;
+    readonly records: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly id: Schema.String;
+        readonly kind: Schema.Literal<"directory">;
+        readonly metadata: Schema.Struct<{
+            readonly uid: Schema.Finite;
+            readonly gid: Schema.Finite;
+            readonly mode: Schema.Finite;
+            readonly atimeNs: Schema.String;
+            readonly mtimeNs: Schema.String;
+            readonly ctimeNs: Schema.String;
+            readonly birthtimeNs: Schema.String;
+        }>;
+        readonly entries: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.String;
+            readonly target: Schema.String;
+        }>>;
+    }>, Schema.Struct<{
+        readonly id: Schema.String;
+        readonly kind: Schema.Literal<"file">;
+        readonly metadata: Schema.Struct<{
+            readonly uid: Schema.Finite;
+            readonly gid: Schema.Finite;
+            readonly mode: Schema.Finite;
+            readonly atimeNs: Schema.String;
+            readonly mtimeNs: Schema.String;
+            readonly ctimeNs: Schema.String;
+            readonly birthtimeNs: Schema.String;
+        }>;
+        readonly data: Schema.String;
+    }>, Schema.Struct<{
+        readonly id: Schema.String;
+        readonly kind: Schema.Literal<"symlink">;
+        readonly metadata: Schema.Struct<{
+            readonly uid: Schema.Finite;
+            readonly gid: Schema.Finite;
+            readonly mode: Schema.Finite;
+            readonly atimeNs: Schema.String;
+            readonly mtimeNs: Schema.String;
+            readonly ctimeNs: Schema.String;
+            readonly birthtimeNs: Schema.String;
+        }>;
+        readonly target: Schema.String;
+    }>]>>;
+}>;
+/** @internal */
+export type Document = typeof Document.Type;
+/** @internal */
+export declare const decodedLength: (value: string) => number;
+/** @internal */
+export declare const base64: (input: Uint8Array) => string;
+/** @internal */
+export declare const bytes: (value: string) => Uint8Array;
+/** @internal */
+export declare const inspect: (snapshot: Snapshot) => Effect.Effect<Document, ImageError>;
+/** @internal */
+export declare const capture: (input: unknown, limits?: {
+    readonly maxEncodedBytes: number;
+    readonly maxRecords: number;
+    readonly maxEntries: number;
+    readonly maxDecodedBytes: number;
+} | undefined) => Effect.Effect<Snapshot, ImageError, never>;
+/** @internal */
+export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8Array<ArrayBuffer>, ImageError, never>;
+/** @internal */
+export declare const decodeSnapshot: (input: Uint8Array<ArrayBufferLike>, limits: {
+    readonly maxEncodedBytes: number;
+    readonly maxRecords: number;
+    readonly maxEntries: number;
+    readonly maxDecodedBytes: number;
+}) => Effect.Effect<Snapshot, ImageError, never>;
+//# sourceMappingURL=image.d.ts.map

package/dist/internal/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/internal/image.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAgB,UAAU,EAAE,KAAK,QAAQ,EAAkB,MAAM,gBAAgB,CAAA;AAaxF,gBAAgB;AAChB,eAAO,MAAM,cAAc;;;;;;;;EAQzB,CAAA;AACF,gBAAgB;AAChB,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD,gBAAgB;AAChB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IASjB,CAAA;AACF,gBAAgB;AAChB,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AACvC,gBAAgB;AAChB,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAKnB,CAAA;AACF,gBAAgB;AAChB,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAO3C,gBAAgB;AAChB,eAAO,MAAM,aAAa,UAAW,MAAM,KAAG,MACmC,CAAA;AACjF,gBAAgB;AAChB,eAAO,MAAM,MAAM,UAAW,UAAU,KAAG,MAU1C,CAAA;AAGD,gBAAgB;AAChB,eAAO,MAAM,KAAK,UAAW,MAAM,KAAG,UAIrC,CAAA;AACD,gBAAgB;AAChB,eAAO,MAAM,OAAO,aAAc,QAAQ,KAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,UAAU,CAI3E,CAAA;AAEJ,gBAAgB;AAChB,eAAO,MAAM,OAAO;;;;;4DAwElB,CAAA;AAEF,gBAAgB;AAChB,eAAO,MAAM,cAAc,mFAKzB,CAAA;AACF,gBAAgB;AAChB,eAAO,MAAM,cAAc;;;;;gDAmB1B,CAAA"}

package/dist/internal/image.js

@@ -0,0 +1,187 @@
+/**
+ * Snapshot validation and serialization used by `VirtualFileSystem`.
+ *
+ * @internal
+ */
+import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import { DecodeLimits, ImageError, SnapshotTypeId } from "../Snapshot.js";
+const natural = Schema.Finite.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+class SnapshotImpl {
+    [SnapshotTypeId] = SnapshotTypeId;
+}
+const integer = Schema.String.check(Schema.isPattern(/^(?:0|-?[1-9][0-9]{0,127})(?![\s\S])/));
+/** @internal */
+export const StoredMetadata = Schema.Struct({
+    uid: natural,
+    gid: natural,
+    mode: natural.check(Schema.isLessThanOrEqualTo(0o7777)),
+    atimeNs: integer,
+    mtimeNs: integer,
+    ctimeNs: integer,
+    birthtimeNs: integer
+});
+const id = Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(128));
+/** @internal */
+export const Record = Schema.Union([
+    Schema.Struct({
+        id,
+        kind: Schema.Literal("directory"),
+        metadata: StoredMetadata,
+        entries: Schema.Array(Schema.Struct({ name: Schema.String, target: id }))
+    }),
+    Schema.Struct({ id, kind: Schema.Literal("file"), metadata: StoredMetadata, data: Schema.String }),
+    Schema.Struct({ id, kind: Schema.Literal("symlink"), metadata: StoredMetadata, target: Schema.String })
+]);
+/** @internal */
+export const Document = Schema.Struct({
+    format: Schema.Literal("effect-vfs"),
+    version: Schema.Literal(1),
+    root: id,
+    records: Schema.Array(Record)
+});
+const snapshots = new WeakMap();
+const canonicalBase64Tail = /^(?:[A-Za-z0-9+/]{4}|[A-Za-z0-9+/][AQgw]==|[A-Za-z0-9+/]{2}[AEIMQUYcgkosw048]=)?(?![\s\S])/;
+// Only the final quartet can contain padding. Scanning the alphabet separately avoids
+// the regexp stack growth caused by repeating a four-character group over large files.
+const canonicalBase64 = (value) => value.length % 4 === 0 && !/[^A-Za-z0-9+/]/.test(value.slice(0, -4)) && canonicalBase64Tail.test(value.slice(-4));
+/** @internal */
+export const decodedLength = (value) => value.length / 4 * 3 - (value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0);
+/** @internal */
+export const base64 = (input) => {
+    // Effect's encoder concatenates individual characters. Join bounded chunks so snapshots
+    // retain flat strings instead of those intermediate string chains. A multiple of three
+    // keeps padding in the final chunk only, preserving canonical base64.
+    const chunkBytes = 12_288;
+    const chunks = [];
+    for (let offset = 0; offset < input.length; offset += chunkBytes) {
+        chunks.push(Encoding.encodeBase64(input.subarray(offset, offset + chunkBytes)));
+    }
+    return chunks.join("");
+};
+const error = (code, field) => new ImageError({ code, ...(field === undefined ? {} : { field }) });
+/** @internal */
+export const bytes = (value) => {
+    const result = Encoding.decodeBase64(value);
+    if (Result.isFailure(result))
+        throw new Error("Invalid trusted snapshot base64");
+    return result.success;
+};
+/** @internal */
+export const inspect = (snapshot) => Effect.suspend(() => {
+    const document = snapshots.get(snapshot);
+    return document === undefined ? Effect.fail(error("InvalidStructure", "snapshot")) : Effect.succeed(document);
+});
+/** @internal */
+export const capture = Effect.fnUntraced(function* (input, limits) {
+    const decoded = Schema.decodeUnknownResult(Document, { onExcessProperty: "error" })(input);
+    if (Result.isFailure(decoded))
+        return yield* error("InvalidStructure");
+    const document = decoded.success;
+    const records = new Map();
+    let entries = 0;
+    let payload = 0;
+    if (limits !== undefined && document.records.length > limits.maxRecords) {
+        return yield* error("LimitExceeded", "records");
+    }
+    for (const record of document.records) {
+        if (records.has(record.id))
+            return yield* error("InvalidStructure", "id");
+        records.set(record.id, record);
+        if (record.kind === "directory")
+            entries += record.entries.length;
+    }
+    if (limits !== undefined && entries > limits.maxEntries)
+        return yield* error("LimitExceeded", "entries");
+    // Count every payload before allocating any decoded payload buffer.
+    for (const record of document.records) {
+        const values = record.kind === "directory"
+            ? record.entries.map((entry) => entry.name)
+            : [record.kind === "file" ? record.data : record.target];
+        for (const value of values) {
+            if (!canonicalBase64(value))
+                return yield* error("InvalidEncoding", record.id);
+            payload += decodedLength(value);
+            if (!Number.isSafeInteger(payload) || (limits !== undefined && payload > limits.maxDecodedBytes)) {
+                return yield* error("LimitExceeded", "bytes");
+            }
+        }
+    }
+    const root = records.get(document.root);
+    if (root?.kind !== "directory")
+        return yield* error("InvalidStructure", "root");
+    const parents = new Map();
+    for (const record of document.records) {
+        if (record.kind === "directory") {
+            const names = new Set();
+            for (const entry of record.entries) {
+                if (names.has(entry.name) || decodedLength(entry.name) < 1 || decodedLength(entry.name) > 255) {
+                    return yield* error("InvalidStructure", "name");
+                }
+                names.add(entry.name);
+                const name = bytes(entry.name);
+                if (name.includes(0) || name.includes(47) || (name.length === 1 && name[0] === 46) ||
+                    (name.length === 2 && name[0] === 46 && name[1] === 46))
+                    return yield* error("InvalidStructure", "name");
+                const target = records.get(entry.target);
+                if (target === undefined)
+                    return yield* error("InvalidStructure", "target");
+                parents.set(target.id, (parents.get(target.id) ?? 0) + 1);
+            }
+        }
+        else if (record.kind === "symlink" && bytes(record.target).includes(0)) {
+            return yield* error("InvalidStructure", "symlink");
+        }
+    }
+    if (parents.has(root.id))
+        return yield* error("InvalidStructure", "root");
+    for (const record of document.records) {
+        if (record !== root && (record.kind === "directory" ? parents.get(record.id) !== 1 : !parents.has(record.id))) {
+            return yield* error("InvalidStructure", "parent");
+        }
+    }
+    const visited = new Set();
+    const pending = [root.id];
+    while (pending.length > 0) {
+        const next = pending.pop();
+        if (next === undefined || visited.has(next))
+            continue;
+        visited.add(next);
+        const record = records.get(next);
+        if (record?.kind === "directory") {
+            for (const entry of record.entries)
+                pending.push(entry.target);
+        }
+    }
+    if (visited.size !== records.size)
+        return yield* error("InvalidStructure", "reachability");
+    const snapshot = Object.freeze(new SnapshotImpl());
+    snapshots.set(snapshot, document);
+    return snapshot;
+});
+/** @internal */
+export const encodeSnapshot = Effect.fn("VirtualFileSystem.encodeSnapshot")(function* (snapshot) {
+    const text = yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown))(yield* inspect(snapshot)).pipe(Effect.mapError(() => error("InvalidStructure")));
+    return new TextEncoder().encode(text);
+});
+/** @internal */
+export const decodeSnapshot = Effect.fn("VirtualFileSystem.decodeSnapshot")(function* (input, limits) {
+    const checked = Schema.decodeResult(DecodeLimits, { onExcessProperty: "error" })(limits);
+    if (Result.isFailure(checked))
+        return yield* error("InvalidStructure", "limits");
+    if (!(input instanceof Uint8Array) || !(input.buffer instanceof ArrayBuffer))
+        return yield* error("InvalidEncoding");
+    if (input.byteLength > checked.success.maxEncodedBytes)
+        return yield* error("LimitExceeded", "encodedBytes");
+    const text = yield* Effect.try({
+        try: () => new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(input)),
+        catch: () => error("InvalidEncoding")
+    });
+    const value = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe(Effect.mapError(() => error("InvalidEncoding")));
+    if (typeof value === "object" && value !== null && "format" in value && value.format === "effect-vfs" &&
+        "version" in value && value.version !== 1)
+        return yield* error("UnsupportedVersion");
+    return yield* capture(value, checked.success);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@effect-vfs/core",
+  "version": "0.0.1",
+  "description": "A runtime-neutral virtual filesystem core for Effect.",
+  "homepage": "https://github.com/lloydrichards/effect-virtual-fs#readme",
+  "bugs": {
+    "url": "https://github.com/lloydrichards/effect-virtual-fs/issues"
+  },
+  "keywords": ["effect", "filesystem", "virtual-filesystem", "typescript"],
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json && tsc --project compatibility/node-next/tsconfig.json",
+    "clean": "git clean -xdf .cache .turbo dist node_modules tsconfig.tsbuildinfo",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.112"
+  },
+  "devDependencies": {
+    "@repo/config-typescript": "workspace:*",
+    "@effect/vitest": "4.0.0-rc.112",
+    "effect": "4.0.0-rc.112"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./VirtualFileSystem": {
+      "types": "./dist/VirtualFileSystem.d.ts",
+      "import": "./dist/VirtualFileSystem.js"
+    },
+    "./internal/*": null,
+    "./index": null,
+    "./*/index": null,
+    "./package.json": "./package.json"
+  },
+  "files": ["dist/**", "README.md", "LICENSE"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lloydrichards/effect-virtual-fs.git",
+    "directory": "packages/core"
+  }
+}