@kdrgny/justjson-astro 1.6.0

package/README.md

@@ -0,0 +1,102 @@
+<div align="center">
+
+# @kdrgny/justjson-astro
+
+**Astro content loader for [JustJSON](https://github.com/kdrgny-dev/justjson).**
+
+Your `content/` folder becomes typed Astro content collections — no glue code.
+
+</div>
+
+---
+
+## Install
+
+```bash
+npm install @kdrgny/justjson-astro
+```
+
+## Use
+
+One line in `src/content.config.ts`:
+
+```ts
+import { justjsonCollections } from '@kdrgny/justjson-astro'
+
+export const collections = await justjsonCollections()
+```
+
+Every collection and singleton in your JustJSON schema becomes an Astro
+collection, with a Zod schema derived from your field definitions:
+
+```astro
+---
+import { getCollection, getEntry } from 'astro:content'
+
+const posts = await getCollection('posts')
+const settings = await getEntry('settings', 'settings')
+---
+<h1>{settings?.data.title}</h1>
+{posts.map((post) => <a href={`/posts/${post.id}`}>{post.data.title}</a>)}
+```
+
+`post.data` is fully typed. A field marked required in the editor is required in
+the type; everything else is optional:
+
+```ts
+{ title: string; slug: string; date?: string; body?: string; _status?: 'draft' | 'published' }
+```
+
+## What you get
+
+| | |
+|---|---|
+| **Typed content** | Field types and required flags come straight from `_schema.json`. |
+| **Drafts skipped** | Entries marked draft in the editor never reach your build. |
+| **Live updates** | Save in the JustJSON editor and the dev server updates — no restart. |
+| **Singletons** | A singleton becomes a one-entry collection; read it with `getEntry`. |
+| **Safe when empty** | No schema yet? The build still succeeds with no collections. |
+
+Entry `id` is the filename without `.json` — ready for `[slug].astro` routes.
+
+## Options
+
+`justjsonCollections()` takes an optional config:
+
+```ts
+export const collections = await justjsonCollections({
+  drafts: true,        // include draft entries (default: false)
+  contentDir: 'data',  // content folder, relative to the project root
+  root: process.cwd(), // project root
+})
+```
+
+For a single collection, use the loader directly:
+
+```ts
+import { defineCollection } from 'astro:content'
+import { justjson } from '@kdrgny/justjson-astro'
+
+export const collections = {
+  posts: defineCollection({ loader: justjson({ collection: 'posts' }) }),
+  settings: defineCollection({ loader: justjson({ singleton: 'settings' }) }),
+}
+```
+
+## Field type mapping
+
+| JustJSON | Astro / Zod |
+|---|---|
+| `text` · `richtext` · `date` · `image` · `url` · `email` · `color` | `string` |
+| `number` | `number` |
+| `boolean` | `boolean` |
+| `select` | `enum` of your options (or `string` if none) |
+| `relation` · `list` | `string[]` |
+| `group` | nested object |
+
+Format checks (is this a real URL?) are left to `justjson validate` on purpose,
+so a typo in one entry never breaks your build in a surprising place.
+
+## License
+
+[MIT](https://github.com/kdrgny-dev/justjson/blob/main/LICENSE) © Kadir Günay

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { Loader } from 'astro/loaders';
+import { defineCollection } from 'astro/content/config';
+import { Field } from '@justjson/core';
+import { z } from 'zod';
+
+interface JustJsonLoaderOptions {
+    /** Yüklenecek koleksiyonun şemadaki adı. `singleton` ile birlikte kullanılmaz. */
+    collection?: string;
+    /** Yüklenecek tekil kaydın şemadaki adı. Tek entry'li bir koleksiyon olarak gelir. */
+    singleton?: string;
+    /** Proje kökü. Verilmezse Astro'nun `config.root`'u kullanılır. */
+    root?: string | URL;
+    /** İçerik klasörü, köke göreli (varsayılan: "content"). */
+    contentDir?: string;
+    /** true ise `_status: 'draft'` kayıtlar da yüklenir. */
+    drafts?: boolean;
+}
+/**
+ * Astro içerik koleksiyonlarını JustJSON'un `content/` klasöründen besler.
+ * Şemadaki alanlardan zod şeması üretir, böylece `entry.data` tam tipli gelir.
+ */
+declare function justjson(options: JustJsonLoaderOptions): Loader;
+
+interface JustJsonCollectionsOptions {
+    /** Proje kökü (varsayılan: process.cwd() — `astro dev`/`build` buradan çalışır). */
+    root?: string | URL;
+    /** İçerik klasörü, köke göreli (varsayılan: "content"). */
+    contentDir?: string;
+    /** true ise taslak kayıtlar da yüklenir. */
+    drafts?: boolean;
+}
+/** Astro'nun `collections` export'unun beklediği şekil. */
+type CollectionDefinition = ReturnType<typeof defineCollection>;
+/**
+ * `content/_schema.json`'daki her koleksiyon ve tekil kayıt için bir Astro
+ * koleksiyonu üretir — content.config.ts'te tek satır yeter.
+ *
+ * Şema yoksa boş nesne döner: JustJSON'u henüz çalıştırmamış bir projede
+ * `astro build` kırılmaz.
+ */
+declare function justjsonCollections(options?: JustJsonCollectionsOptions): Promise<Record<string, CollectionDefinition>>;
+
+/** JustJSON alanlarını Astro'nun kullanacağı bir zod nesnesine çevirir. */
+declare function fieldsToZod(fields: Field[]): z.ZodObject<z.ZodRawShape>;
+
+export { type CollectionDefinition, type JustJsonCollectionsOptions, type JustJsonLoaderOptions, fieldsToZod, justjson, justjsonCollections };

package/dist/index.js

@@ -0,0 +1,280 @@
+// src/loader.ts
+import { readFile, readdir } from "fs/promises";
+import { fileURLToPath } from "url";
+
+// ../core/dist/index.js
+import { z } from "zod";
+var JustJsonError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var SchemaError = class extends JustJsonError {
+};
+var fieldTypes = [
+  "text",
+  "richtext",
+  "number",
+  "boolean",
+  "date",
+  "select",
+  "relation",
+  "image",
+  "url",
+  "email",
+  "list",
+  "color",
+  "group"
+];
+var zField = z.lazy(
+  () => z.object({
+    key: z.string().min(1),
+    label: z.string().optional(),
+    type: z.enum(fieldTypes),
+    required: z.boolean().optional(),
+    options: z.array(z.string()).optional(),
+    to: z.string().optional(),
+    fields: z.array(zField).optional()
+  }).superRefine((field, ctx) => {
+    if (field.type === "select" && (!field.options || field.options.length === 0)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a select field requires options" });
+    }
+    if (field.type === "relation" && !field.to) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'a relation field requires "to"' });
+    }
+    if (field.type === "group" && (!field.fields || field.fields.length === 0)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: "a group field requires fields" });
+    }
+  })
+);
+var zCollection = z.object({
+  name: z.string().min(1),
+  label: z.string().optional(),
+  path: z.string().min(1),
+  fields: z.array(zField)
+});
+var zSingleton = z.object({
+  name: z.string().min(1),
+  label: z.string().optional(),
+  path: z.string().min(1),
+  fields: z.array(zField)
+});
+var zSchema = z.object({
+  version: z.literal(1),
+  collections: z.array(zCollection),
+  singletons: z.array(zSingleton)
+}).superRefine((schema, ctx) => {
+  const names = /* @__PURE__ */ new Set();
+  const paths = /* @__PURE__ */ new Set();
+  const collectionNames = new Set(schema.collections.map((c) => c.name));
+  const containers = [...schema.collections, ...schema.singletons];
+  for (const c of containers) {
+    if (names.has(c.name)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate name: ${c.name}` });
+    }
+    names.add(c.name);
+    if (c.path.includes("..") || c.path.startsWith("/") || c.path.includes("\\")) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: `unsafe path: ${c.path}` });
+    }
+    if (paths.has(c.path)) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate path: ${c.path}` });
+    }
+    paths.add(c.path);
+    const keys = /* @__PURE__ */ new Set();
+    for (const f of c.fields) {
+      if (keys.has(f.key)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate field key: ${f.key}` });
+      }
+      keys.add(f.key);
+      if (f.type === "relation" && f.to && !collectionNames.has(f.to)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `relation target does not exist: ${f.to}`
+        });
+      }
+    }
+  }
+});
+function parseSchema(input) {
+  const result = zSchema.safeParse(input);
+  if (result.success) return result.data;
+  const lines = result.error.issues.map(
+    (i) => i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message
+  );
+  throw new SchemaError(lines.join("\n"));
+}
+var STATUS_KEY = "_status";
+function entryStatus(data) {
+  return data[STATUS_KEY] === "draft" ? "draft" : "published";
+}
+
+// src/zod-schema.ts
+import { z as z2 } from "zod";
+function base(field) {
+  switch (field.type) {
+    case "number":
+      return z2.number();
+    case "boolean":
+      return z2.boolean();
+    case "relation":
+    case "list":
+      return z2.array(z2.string());
+    case "group":
+      return fieldsToZod(field.fields ?? []);
+    case "select": {
+      const options = field.options ?? [];
+      return options.length > 0 ? z2.enum(options) : z2.string();
+    }
+    default:
+      return z2.string();
+  }
+}
+function fieldsToZod(fields) {
+  const shape = {
+    [STATUS_KEY]: z2.enum(["draft", "published"]).optional()
+  };
+  for (const field of fields) {
+    const type = base(field);
+    shape[field.key] = field.required ? type : type.optional();
+  }
+  return z2.object(shape);
+}
+
+// src/loader.ts
+function toPath(value) {
+  return (typeof value === "string" ? value : fileURLToPath(value)).replace(/\/$/, "");
+}
+async function readSchema(root, contentDir) {
+  let raw;
+  try {
+    raw = await readFile(`${root}/${contentDir}/_schema.json`, "utf8");
+  } catch {
+    throw new Error(
+      `justjson: no schema found at ${contentDir}/_schema.json \u2014 run \`npx @kdrgny/justjson\` in this folder first.`
+    );
+  }
+  return parseSchema(JSON.parse(raw));
+}
+function justjson(options) {
+  const contentDir = options.contentDir ?? "content";
+  const name = options.collection ?? options.singleton;
+  if (!name) throw new Error("justjson: pass either `collection` or `singleton`.");
+  return {
+    name: "@kdrgny/justjson-astro",
+    schema: async () => {
+      const root = options.root ? toPath(options.root) : process.cwd();
+      try {
+        const schema = await readSchema(root, contentDir);
+        const container = options.singleton ? schema.singletons.find((s) => s.name === name) : schema.collections.find((c) => c.name === name);
+        return fieldsToZod(container?.fields ?? []);
+      } catch {
+        return fieldsToZod([]);
+      }
+    },
+    load: async (ctx) => {
+      const root = toPath(options.root ?? ctx.config.root);
+      const schema = await readSchema(root, contentDir);
+      ctx.store.clear();
+      const sync = async (id, absolute, relative) => {
+        let raw;
+        try {
+          raw = await readFile(absolute, "utf8");
+        } catch {
+          ctx.store.delete(id);
+          return;
+        }
+        const data = JSON.parse(raw);
+        if (!options.drafts && entryStatus(data) === "draft") {
+          ctx.store.delete(id);
+          return;
+        }
+        ctx.store.set({
+          id,
+          data: await ctx.parseData({ id, data, filePath: relative }),
+          digest: ctx.generateDigest(data),
+          filePath: relative
+        });
+      };
+      if (options.singleton) {
+        const single = schema.singletons.find((s) => s.name === name);
+        if (!single) throw new Error(`justjson: singleton "${name}" is not in the schema.`);
+        const absolute = `${root}/${contentDir}/${single.path}`;
+        await sync(name, absolute, `${contentDir}/${single.path}`);
+        watch(ctx, absolute, (changed, event) => {
+          if (changed !== absolute) return;
+          if (event === "unlink") return void ctx.store.delete(name);
+          return sync(name, absolute, `${contentDir}/${single.path}`);
+        });
+        return;
+      }
+      const collection = schema.collections.find((c) => c.name === name);
+      if (!collection) throw new Error(`justjson: collection "${name}" is not in the schema.`);
+      const dir = `${root}/${contentDir}/${collection.path}`;
+      const idFor = (absolute) => absolute.slice(dir.length + 1, -".json".length);
+      const relativeFor = (absolute) => `${contentDir}/${collection.path}/${absolute.slice(dir.length + 1)}`;
+      let files;
+      try {
+        files = (await readdir(dir)).filter((f) => f.endsWith(".json"));
+      } catch {
+        ctx.logger.warn(
+          `justjson: ${contentDir}/${collection.path}/ does not exist yet \u2014 collection is empty.`
+        );
+        files = [];
+      }
+      for (const file of files.sort()) {
+        await sync(file.slice(0, -".json".length), `${dir}/${file}`, relativeFor(`${dir}/${file}`));
+      }
+      watch(ctx, dir, (changed, event) => {
+        if (!changed.startsWith(`${dir}/`) || !changed.endsWith(".json")) return;
+        if (event === "unlink") return void ctx.store.delete(idFor(changed));
+        return sync(idFor(changed), changed, relativeFor(changed));
+      });
+    }
+  };
+}
+function watch(ctx, target, onEvent) {
+  if (!ctx.watcher) return;
+  ctx.watcher.add(target);
+  for (const event of ["change", "add", "unlink"]) {
+    ctx.watcher.on(event, (path) => onEvent(path, event));
+  }
+}
+
+// src/collections.ts
+import { readFile as readFile2 } from "fs/promises";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { defineCollection } from "astro/content/config";
+async function justjsonCollections(options = {}) {
+  const contentDir = options.contentDir ?? "content";
+  const rootValue = options.root ?? process.cwd();
+  const root = (typeof rootValue === "string" ? rootValue : fileURLToPath2(rootValue)).replace(
+    /\/$/,
+    ""
+  );
+  let raw;
+  try {
+    raw = await readFile2(`${root}/${contentDir}/_schema.json`, "utf8");
+  } catch {
+    return {};
+  }
+  const schema = parseSchema(JSON.parse(raw));
+  const shared = { root, contentDir, drafts: options.drafts };
+  const out = {};
+  for (const collection of schema.collections) {
+    out[collection.name] = defineCollection({
+      loader: justjson({ ...shared, collection: collection.name })
+    });
+  }
+  for (const singleton of schema.singletons) {
+    out[singleton.name] = defineCollection({
+      loader: justjson({ ...shared, singleton: singleton.name })
+    });
+  }
+  return out;
+}
+export {
+  fieldsToZod,
+  justjson,
+  justjsonCollections
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@kdrgny/justjson-astro",
+  "version": "1.6.0",
+  "description": "Astro content loader for JustJSON — turn your content/ folder into typed Astro content collections.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Kadir Günay",
+  "homepage": "https://github.com/kdrgny-dev/justjson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kdrgny-dev/justjson.git",
+    "directory": "packages/astro"
+  },
+  "keywords": ["astro", "astro-loader", "astro-integration", "cms", "json", "content", "justjson"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "astro": "^5.0.0"
+  },
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@justjson/core": "workspace:*",
+    "@types/node": "^22.10.2",
+    "astro": "^5.0.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}