@farm.js/content 0.1.0-beta.0

package/dist/index.js

@@ -0,0 +1,135 @@
+import path from "node:path";
+import { definePlugin } from "@farm.js/core/plugin";
+import fg from "fast-glob";
+import { asset } from "./assets.js";
+import { collection, files, isSupportedContentFile } from "./config.js";
+import { loadContentCollections, writeContentServerModule } from "./loader.js";
+const CONTENT_SERVER_ID = "@farm.js/content/server";
+export { asset, collection, files };
+/** Load schema-validated local content as a typed server-only collection registry. */
+export function content(options) {
+    validateOptions(options);
+    let root = process.cwd();
+    let generatedFile = "";
+    let sourceFiles = new Set();
+    const plugin = definePlugin({
+        name: "farm:content",
+        enforce: "pre",
+        async configure(config) {
+            if ((config.plugins ?? []).filter((candidate) => candidate.name === "farm:content").length > 1) {
+                throw new Error("[farm:content] Configure all collections in one content() plugin instance");
+            }
+            root = path.resolve(config.root ?? ".");
+            generatedFile = path.join(root, ".farm", "content", "server.mjs");
+            await rebuild();
+            const vite = config.vite ?? {};
+            return {
+                ...config,
+                vite: {
+                    ...vite,
+                    optimizeDeps: {
+                        ...vite.optimizeDeps,
+                        exclude: [...new Set([CONTENT_SERVER_ID, ...(vite.optimizeDeps?.exclude ?? [])])],
+                    },
+                    plugins: [createContentVitePlugin(), ...(vite.plugins ?? [])],
+                },
+            };
+        },
+    });
+    async function rebuild() {
+        const attemptedSourceFiles = new Set();
+        try {
+            const loaded = await loadContentCollections(root, options.collections, attemptedSourceFiles);
+            await writeContentServerModule(generatedFile, loaded.collections, loaded.assetImports);
+            sourceFiles = new Set(loaded.sourceFiles);
+        }
+        catch (error) {
+            sourceFiles = new Set([...sourceFiles, ...attemptedSourceFiles]);
+            throw error;
+        }
+    }
+    function createContentVitePlugin() {
+        let rebuildQueue = Promise.resolve();
+        return {
+            name: "farm:content-runtime",
+            enforce: "pre",
+            resolveId(id, importer, resolveOptions) {
+                if (id !== CONTENT_SERVER_ID)
+                    return undefined;
+                const environmentName = this.environment?.name;
+                const serverEnvironment = resolveOptions?.ssr || environmentName === "ssr" || environmentName === "rsc";
+                if (!serverEnvironment) {
+                    throw new Error(`[farm:content] ${CONTENT_SERVER_ID} is server-only and cannot be imported into the client environment${importer ? ` by ${importer}` : ""}`);
+                }
+                return generatedFile;
+            },
+            configureServer(server) {
+                const onFile = (event, filePath) => {
+                    if (event !== "add" && event !== "change" && event !== "unlink")
+                        return;
+                    const absoluteFile = path.resolve(filePath);
+                    rebuildQueue = rebuildQueue
+                        .then(async () => {
+                        if (!(await shouldRebuildForFile(root, absoluteFile, event, sourceFiles, options.collections))) {
+                            return;
+                        }
+                        await rebuild();
+                        const modules = server.moduleGraph.getModulesByFile?.(generatedFile);
+                        for (const module of modules ?? [])
+                            server.moduleGraph.invalidateModule(module);
+                        server.ws.send({ type: "full-reload" });
+                    })
+                        .catch((error) => {
+                        const message = error instanceof Error ? error.message : String(error);
+                        server.ws.send({
+                            type: "error",
+                            err: { message, stack: error instanceof Error ? error.stack : undefined },
+                        });
+                    });
+                };
+                server.watcher.on("all", onFile);
+                server.httpServer?.once("close", () => server.watcher.off?.("all", onFile));
+            },
+        };
+    }
+    return plugin;
+}
+async function shouldRebuildForFile(root, filePath, event, sourceFiles, collections) {
+    if (sourceFiles.has(filePath))
+        return true;
+    const relative = path.relative(root, filePath);
+    if (event !== "add" ||
+        relative === "" ||
+        relative.startsWith("..") ||
+        path.isAbsolute(relative) ||
+        !isSupportedContentFile(filePath)) {
+        return false;
+    }
+    for (const definition of Object.values(collections)) {
+        const matches = await fg([...definition.source.patterns], {
+            cwd: root,
+            absolute: true,
+            onlyFiles: true,
+            unique: true,
+            dot: false,
+            followSymbolicLinks: false,
+            ignore: [...definition.source.ignore],
+        });
+        if (matches.some((candidate) => path.resolve(candidate) === filePath))
+            return true;
+    }
+    return false;
+}
+function validateOptions(options) {
+    if (!options || typeof options !== "object" || !options.collections) {
+        throw new TypeError("Content plugin needs a collections object");
+    }
+    if (Object.keys(options.collections).length === 0) {
+        throw new TypeError("Content plugin needs at least one collection");
+    }
+    for (const [name, definition] of Object.entries(options.collections)) {
+        if (!definition || typeof definition !== "object") {
+            throw new TypeError(`Content collection "${name}" must come from collection()`);
+        }
+    }
+}

package/dist/loader.d.ts

@@ -0,0 +1,13 @@
+import { type ContentAssetImport } from "./assets.js";
+import type { ContentCollections, ContentEntry } from "./types.js";
+export interface LoadedContent {
+    readonly collections: Readonly<Record<string, readonly ContentEntry<any>[]>>;
+    readonly sourceFiles: ReadonlySet<string>;
+    readonly assetImports: ReadonlyMap<string, ContentAssetImport>;
+}
+export declare function loadContentCollections(root: string, collections: ContentCollections, sourceFiles?: Set<string>): Promise<LoadedContent>;
+export declare function writeContentServerModule(outputFile: string, collections: Readonly<Record<string, readonly ContentEntry<any>[]>>, assetImports?: ReadonlyMap<string, ContentAssetImport>): Promise<void>;
+type EncodedContentValue = null | boolean | number | string | ["undefined"] | ["date", string] | ["bigint", string] | ["array", EncodedContentValue[]] | ["object", Array<[string, EncodedContentValue]>];
+export declare function encodeContentValue(value: unknown, seen?: Set<object>): EncodedContentValue;
+export {};
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,EAEV,kBAAkB,EAClB,YAAY,EAIb,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7E,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAChE;AAED,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,kBAAkB,EAC/B,WAAW,GAAE,GAAG,CAAC,MAAM,CAAa,GACnC,OAAO,CAAC,aAAa,CAAC,CAexB;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,EACnE,YAAY,GAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAa,GAChE,OAAO,CAAC,IAAI,CAAC,CAgCf;AAoPD,KAAK,mBAAmB,GACpB,IAAI,GACJ,OAAO,GACP,MAAM,GACN,MAAM,GACN,CAAC,WAAW,CAAC,GACb,CAAC,MAAM,EAAE,MAAM,CAAC,GAChB,CAAC,QAAQ,EAAE,MAAM,CAAC,GAClB,CAAC,OAAO,EAAE,mBAAmB,EAAE,CAAC,GAChC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAErD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,cAAoB,GAAG,mBAAmB,CAmChG"}

package/dist/loader.js

@@ -0,0 +1,360 @@
+import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import fg from "fast-glob";
+import matter from "gray-matter";
+import { parse as parseYaml } from "yaml";
+import { mergeContentAssetData, resolveContentAssetFields, splitContentAssetInput, } from "./assets.js";
+import { isSupportedContentFile } from "./config.js";
+import { resolveMarkdownAssets } from "./markdown-assets.js";
+export async function loadContentCollections(root, collections, sourceFiles = new Set()) {
+    const loaded = Object.create(null);
+    const assetImports = new Map();
+    for (const [name, definition] of Object.entries(collections)) {
+        validateCollectionName(name);
+        const entries = await loadCollection(root, name, definition, sourceFiles, assetImports);
+        loaded[name] = Object.freeze(entries);
+    }
+    return {
+        collections: Object.freeze(loaded),
+        sourceFiles,
+        assetImports,
+    };
+}
+export async function writeContentServerModule(outputFile, collections, assetImports = new Map()) {
+    const outputDirectory = path.dirname(outputFile);
+    await mkdir(outputDirectory, { recursive: true });
+    const actualOutputDirectory = await realpath(outputDirectory);
+    const encoded = encodeContentValue(collections);
+    const imports = [...assetImports.values()].sort((left, right) => left.token.localeCompare(right.token));
+    const importSource = imports
+        .map((asset, index) => `import farmContentAsset${index} from ${JSON.stringify(`${toViteImportSpecifier(actualOutputDirectory, asset.filePath)}?url`)};`)
+        .join("\n");
+    const assetUrls = imports.length
+        ? `, { ${imports
+            .map((asset, index) => `${JSON.stringify(asset.token)}: farmContentAsset${index}`)
+            .join(", ")} }`
+        : "";
+    const source = `// Generated by @farm.js/content. Do not edit.
+import { createContentRuntime, decodeContentValue } from "@farm.js/content/internal/runtime";
+${importSource ? `\n${importSource}` : ""}
+
+const runtime = createContentRuntime(decodeContentValue(${JSON.stringify(encoded)}${assetUrls}));
+
+export const getCollection = runtime.getCollection;
+export const getEntry = runtime.getEntry;
+export const getEntryOrThrow = runtime.getEntryOrThrow;
+`;
+    await writeFileIfChanged(outputFile, source);
+}
+async function loadCollection(root, name, definition, sourceFiles, assetImports) {
+    const source = definition.source;
+    const relativeFiles = await fg([...source.patterns], {
+        cwd: root,
+        absolute: false,
+        onlyFiles: true,
+        unique: true,
+        dot: false,
+        followSymbolicLinks: false,
+        ignore: [...source.ignore],
+    });
+    const files = relativeFiles
+        .map(normalizePath)
+        .filter(isSupportedContentFile)
+        .sort((left, right) => left.localeCompare(right));
+    const entries = [];
+    const ids = new Map();
+    for (const relativeFile of files) {
+        const absoluteFile = path.resolve(root, relativeFile);
+        const id = contentEntryId(relativeFile, source);
+        const duplicate = ids.get(id);
+        if (duplicate) {
+            throw new Error(`[farm:content] Collection "${name}" has duplicate entry ID "${id}" from ${duplicate} and ${relativeFile}`);
+        }
+        ids.set(id, relativeFile);
+        sourceFiles.add(absoluteFile);
+        const parsed = await parseContentFile(absoluteFile, relativeFile);
+        const assetContext = {
+            root,
+            collectionName: name,
+            sourceFile: relativeFile,
+            sourceFiles,
+            imports: assetImports,
+        };
+        const typedAssets = definition.assets && definition.assets !== true ? definition.assets : undefined;
+        let schemaInput = parsed.data;
+        let assetInput;
+        if (typedAssets) {
+            try {
+                const split = splitContentAssetInput(parsed.data, typedAssets);
+                schemaInput = split.schemaInput;
+                assetInput = split.assetInput;
+            }
+            catch (error) {
+                throw new Error(`[farm:content] Collection ${JSON.stringify(name)} rejected ${relativeFile}: ${errorMessage(error)}`, { cause: error });
+            }
+        }
+        const validatedData = await validateContentData(definition.schema, schemaInput, name, relativeFile);
+        const data = typedAssets
+            ? mergeContentAssetData(validatedData, await resolveContentAssetFields(typedAssets, assetInput, assetContext), assetContext)
+            : validatedData;
+        const resolvedBody = definition.assets && /\.mdx?$/i.test(relativeFile)
+            ? await resolveMarkdownAssets(parsed.body, assetContext)
+            : { body: parsed.body, assets: Object.freeze([]) };
+        const baseEntry = {
+            id,
+            data,
+            body: resolvedBody.body,
+            bodyAssets: resolvedBody.assets,
+            filePath: relativeFile,
+            words: countWords(resolvedBody.body),
+        };
+        const transformed = definition.transform
+            ? await definition.transform(baseEntry)
+            : baseEntry.data;
+        entries.push(Object.freeze({
+            id,
+            data: freezeContentValue(transformed),
+            body: resolvedBody.body,
+            bodyAssets: freezeContentValue(resolvedBody.assets),
+            filePath: relativeFile,
+        }));
+    }
+    return entries;
+}
+async function parseContentFile(absoluteFile, relativeFile) {
+    const source = await readFile(absoluteFile, "utf8");
+    const extension = path.extname(relativeFile).toLowerCase();
+    try {
+        if (extension === ".md" || extension === ".mdx") {
+            const parsed = matter(source);
+            return { data: parsed.data, body: parsed.content };
+        }
+        if (extension === ".json") {
+            return { data: JSON.parse(source), body: "" };
+        }
+        if (extension === ".yaml" || extension === ".yml") {
+            return { data: parseYaml(source), body: "" };
+        }
+    }
+    catch (error) {
+        throw new Error(`[farm:content] Could not parse ${relativeFile}: ${errorMessage(error)}`, {
+            cause: error,
+        });
+    }
+    throw new Error(`[farm:content] Unsupported content file: ${relativeFile}`);
+}
+async function validateContentData(schema, input, collectionName, filePath) {
+    try {
+        const standard = schema["~standard"];
+        if (standard) {
+            const result = await standard.validate(input);
+            if (result.issues?.length) {
+                throw new ContentValidationError(formatIssues(result.issues));
+            }
+            return result.value;
+        }
+        if (schema.parseAsync)
+            return await schema.parseAsync(input);
+        if (schema.parse)
+            return schema.parse(input);
+    }
+    catch (error) {
+        const details = error instanceof ContentValidationError ? error.message : formatSchemaError(error);
+        throw new Error(`[farm:content] Collection "${collectionName}" rejected ${filePath}: ${details}`, { cause: error });
+    }
+    throw new TypeError(`[farm:content] Collection "${collectionName}" has an invalid schema`);
+}
+class ContentValidationError extends Error {
+}
+function formatSchemaError(error) {
+    if (error && typeof error === "object" && "issues" in error) {
+        const issues = error.issues;
+        if (issues?.length)
+            return formatIssues(issues);
+    }
+    return errorMessage(error);
+}
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const pathLabel = issue.path?.length
+            ? `${issue.path.map(formatIssuePathSegment).join(".")}: `
+            : "";
+        return `${pathLabel}${issue.message}`;
+    })
+        .join("; ");
+}
+function formatIssuePathSegment(segment) {
+    if (segment && typeof segment === "object" && "key" in segment) {
+        return String(segment.key);
+    }
+    return String(segment);
+}
+function contentEntryId(filePath, source) {
+    const base = source.base ?? inferCommonSourceBase(source.patterns);
+    const relative = base && base !== "." ? path.posix.relative(base, filePath) : filePath;
+    if (relative === ".." || relative.startsWith("../") || path.posix.isAbsolute(relative)) {
+        throw new Error(`[farm:content] Source file ${filePath} is outside the configured content base ${base}`);
+    }
+    return relative.replace(/\.(?:mdx?|json|ya?ml)$/i, "").replace(/(?:^|\/)index$/, "") || "index";
+}
+function inferCommonSourceBase(patterns) {
+    const bases = patterns.map(inferSourceBase).map((base) => base.split("/").filter(Boolean));
+    const [first = [], ...rest] = bases;
+    const common = [];
+    for (let index = 0; index < first.length; index += 1) {
+        const segment = first[index];
+        if (!rest.every((base) => base[index] === segment))
+            break;
+        common.push(segment);
+    }
+    return common.join("/");
+}
+function inferSourceBase(pattern) {
+    const segments = normalizePath(pattern).split("/");
+    const staticSegments = [];
+    for (const segment of segments) {
+        if (/[*?{}()[\]!]/.test(segment))
+            break;
+        staticSegments.push(segment);
+    }
+    if (staticSegments.length > 0 && path.posix.extname(staticSegments.at(-1) ?? "")) {
+        staticSegments.pop();
+    }
+    return staticSegments.join("/");
+}
+function validateCollectionName(name) {
+    if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) {
+        throw new TypeError(`[farm:content] Collection name "${name}" must start with a letter and contain only letters, numbers, underscores, or hyphens`);
+    }
+}
+function countWords(body) {
+    const normalized = body.trim();
+    return normalized ? normalized.split(/\s+/).length : 0;
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, "/");
+}
+function toViteImportSpecifier(outputDirectory, filePath) {
+    const relative = normalizePath(path.relative(outputDirectory, filePath));
+    return relative.startsWith(".") ? relative : `./${relative}`;
+}
+export function encodeContentValue(value, seen = new Set()) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError("[farm:content] Content data cannot contain non-finite numbers");
+        }
+        return value;
+    }
+    if (value === undefined)
+        return ["undefined"];
+    if (typeof value === "bigint")
+        return ["bigint", value.toString()];
+    if (typeof value === "function" || typeof value === "symbol") {
+        throw new TypeError(`[farm:content] Content data cannot contain ${typeof value} values`);
+    }
+    if (value instanceof Date) {
+        if (Number.isNaN(value.getTime())) {
+            throw new TypeError("[farm:content] Content data cannot contain an invalid Date");
+        }
+        return ["date", value.toISOString()];
+    }
+    if (seen.has(value)) {
+        throw new TypeError("[farm:content] Content data cannot contain circular references");
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value))
+            return ["array", encodeArray(value, seen)];
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError(`[farm:content] Content data must use plain objects, arrays, dates, bigints, and primitive values`);
+        }
+        return ["object", encodeObject(value, seen)];
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+function encodeArray(value, seen) {
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const keys = Reflect.ownKeys(value).filter((key) => key !== "length");
+    for (const key of keys) {
+        if (typeof key === "symbol" || !isArrayIndex(key, value.length)) {
+            throw new TypeError("[farm:content] Content arrays cannot contain custom properties");
+        }
+    }
+    return Array.from({ length: value.length }, (_, index) => {
+        const descriptor = descriptors[index];
+        if (!descriptor) {
+            throw new TypeError("[farm:content] Content data cannot contain sparse arrays");
+        }
+        assertSerializableProperty(descriptor);
+        return encodeContentValue(descriptor.value, seen);
+    });
+}
+function encodeObject(value, seen) {
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    return Reflect.ownKeys(value).map((key) => {
+        if (typeof key === "symbol") {
+            throw new TypeError("[farm:content] Content objects cannot contain symbol keys");
+        }
+        const descriptor = descriptors[key];
+        assertSerializableProperty(descriptor);
+        return [key, encodeContentValue(descriptor.value, seen)];
+    });
+}
+function assertSerializableProperty(descriptor) {
+    if (!("value" in descriptor)) {
+        throw new TypeError("[farm:content] Content data cannot contain getters or setters");
+    }
+    if (!descriptor.enumerable) {
+        throw new TypeError("[farm:content] Content data cannot contain non-enumerable properties");
+    }
+}
+function isArrayIndex(key, length) {
+    const index = Number(key);
+    return Number.isInteger(index) && index >= 0 && index < length && String(index) === key;
+}
+function freezeContentValue(value, ancestors = new Set()) {
+    if (!value || typeof value !== "object" || Object.isFrozen(value))
+        return value;
+    if (ancestors.has(value)) {
+        throw new TypeError("[farm:content] Content data cannot contain circular references");
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(value))) {
+                if ("value" in descriptor)
+                    freezeContentValue(descriptor.value, ancestors);
+            }
+        }
+        else if (!(value instanceof Date)) {
+            for (const descriptor of Object.values(Object.getOwnPropertyDescriptors(value))) {
+                if ("value" in descriptor)
+                    freezeContentValue(descriptor.value, ancestors);
+            }
+        }
+        return Object.freeze(value);
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+async function writeFileIfChanged(filePath, source) {
+    try {
+        if ((await readFile(filePath, "utf8")) === source)
+            return;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    await writeFile(filePath, source, "utf8");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/markdown-assets.d.ts

@@ -0,0 +1,7 @@
+import { type ContentAssetContext } from "./assets.js";
+import type { ContentAssetValue } from "./types.js";
+export declare function resolveMarkdownAssets(body: string, context: ContentAssetContext): Promise<{
+    body: string;
+    assets: readonly ContentAssetValue[];
+}>;
+//# sourceMappingURL=markdown-assets.d.ts.map

package/dist/markdown-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-assets.d.ts","sourceRoot":"","sources":["../src/markdown-assets.ts"],"names":[],"mappings":"AACA,OAAO,EAAuB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AA8BpD,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAAE,CAAC,CAsCjE"}