@easy-cms/plugin-redirects 0.18.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanawoot K.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @easy-cms/plugin-redirects
+
+Redirects for [Easy CMS](https://maritonx.github.io/easy-cms/): a Redirects list under Settings
+in the admin, and automatic redirects when a published page's address changes.
+
+```ts
+import { redirectsPlugin } from '@easy-cms/plugin-redirects'
+
+export default defineConfig({
+  // …
+  plugins: [
+    redirectsPlugin({
+      collections: ['posts'],
+      url: ({ doc }) => (doc.slug ? `/posts/${doc.slug}` : null),
+    }),
+  ],
+})
+```
+
+```ts
+import { resolveRedirect } from '@easy-cms/plugin-redirects'
+
+// In your app's middleware
+const redirect = await resolveRedirect(cms, new URL(request.url))
+if (redirect) return Response.redirect(new URL(redirect.location, request.url), redirect.status)
+```
+
+See [Redirects](https://maritonx.github.io/easy-cms/guide/redirects).

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+import { Plugin } from '@easy-cms/core';
+
+type Doc$1 = Record<string, unknown>;
+interface UrlArgs {
+    readonly collection: string;
+    /** The document, as read for visitors. */
+    readonly doc: Doc$1;
+    /** The content locale, or `null` without localization. */
+    readonly locale: string | null;
+}
+interface RedirectsPluginOptions {
+    /**
+     * Collections a redirect can point to, as a document instead of a fixed address. The
+     * redirect follows the document when its address changes, and pages in these collections
+     * get a redirect automatically when their address changes (see `autoRedirect`).
+     */
+    readonly collections?: readonly string[];
+    /**
+     * A document's address, e.g. `({ doc }) => \`/posts/${doc.slug}\``. Needed with `collections`;
+     * share one function with the SEO plugin's `generateURL`.
+     */
+    readonly url?: (args: UrlArgs) => string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * When a published page's address changes (a new slug), add a redirect from the old address.
+     * Default true for all `collections`; or a list of them.
+     */
+    readonly autoRedirect?: boolean | readonly string[];
+    /** Slug of the redirects collection. Default `redirects`. */
+    readonly slug?: string;
+    /**
+     * How long a server keeps the redirects in memory, in ms. Changes clear it at once on the
+     * server that made them; other servers (serverless instances) catch up within this time.
+     * Default 60000.
+     */
+    readonly cacheTTL?: number;
+}
+/**
+ * A `redirects` collection under Settings in the admin, `resolveRedirect()` for your app's
+ * middleware, and automatic redirects when a page's address changes.
+ */
+declare function redirectsPlugin(options?: RedirectsPluginOptions): Plugin;
+
+type Doc = Record<string, unknown>;
+/** The part of the Local API the helpers use; a structural type. */
+interface RedirectsCMS {
+    readonly config: {
+        readonly endpoints: readonly {
+            readonly handler: unknown;
+        }[];
+    };
+    find(collection: string, options: Record<string, unknown>): Promise<{
+        docs: Doc[];
+        hasNextPage: boolean;
+    }>;
+    findById(collection: string, id: string | number, options?: Record<string, unknown>): Promise<Doc | null>;
+}
+interface Redirect {
+    /** Where to send the visitor: a path on the site, or a full URL. */
+    readonly location: string;
+    readonly status: 301 | 302 | 307 | 308;
+}
+/**
+ * A path as redirects store it: the pathname only (no query or fragment), no trailing slash.
+ * `null` when it isn't a path.
+ */
+declare function normalizePath(input: string): string | null;
+/** Forgets the cached redirects, so the next request reads them again. */
+declare function clearRedirects(cms: object): void;
+/**
+ * The redirect for a request's path, or `null`. Pass the request's URL to keep its query
+ * string. Redirects are read once and kept in memory (see `cacheTTL`), so calling this on every
+ * request is cheap.
+ *
+ * ```ts
+ * const redirect = await resolveRedirect(cms, new URL(request.url))
+ * if (redirect) return Response.redirect(new URL(redirect.location, request.url), redirect.status)
+ * ```
+ */
+declare function resolveRedirect(cms: RedirectsCMS, input: string | URL): Promise<Redirect | null>;
+
+declare const STATUSES: readonly [301, 302, 307, 308];
+type RedirectStatus = (typeof STATUSES)[number];
+
+export { type Redirect, type RedirectStatus, type RedirectsPluginOptions, STATUSES, type UrlArgs, clearRedirects, normalizePath, redirectsPlugin, resolveRedirect };

package/dist/index.js

@@ -0,0 +1,284 @@
+// src/shared.ts
+var REDIRECTS_SOURCE = /* @__PURE__ */ Symbol.for("easy-cms.plugin-redirects.source");
+var STATUSES = [301, 302, 307, 308];
+var targetField = (collection) => `to_${collection.replace(/-/g, "_")}`;
+
+// src/resolve.ts
+function normalizePath(input) {
+  const value = input.trim();
+  if (!value) return null;
+  let url;
+  try {
+    url = new URL(value, "http://site.invalid");
+  } catch {
+    return null;
+  }
+  if (!/^(\/|https?:\/\/)/i.test(value)) return null;
+  return url.pathname.replace(/\/+$/, "") || "/";
+}
+var CACHE = /* @__PURE__ */ Symbol.for("easy-cms.plugin-redirects.cache");
+function clearRedirects(cms) {
+  delete cms[CACHE];
+}
+async function resolveRedirect(cms, input) {
+  const url = typeof input === "string" ? safeUrl(input) : input;
+  if (!url) return null;
+  const path = normalizePath(url.pathname);
+  if (!path) return null;
+  const found = (await redirects(cms)).get(path);
+  if (!found) return null;
+  const location = url.search && !found.location.includes("?") ? found.location + url.search : found.location;
+  return { location, status: found.status };
+}
+function safeUrl(input) {
+  try {
+    return new URL(input, "http://site.invalid");
+  } catch {
+    return null;
+  }
+}
+function findSource(cms) {
+  for (const endpoint of cms.config.endpoints) {
+    const source = endpoint.handler[REDIRECTS_SOURCE];
+    if (source) return source;
+  }
+  throw new Error("resolveRedirect: add redirectsPlugin() to the plugins in your Easy CMS config");
+}
+function redirects(cms) {
+  const source = findSource(cms);
+  const holder = cms;
+  const cached = holder[CACHE];
+  if (cached && Date.now() - cached.at < source.cacheTTL) return cached.map;
+  const map = load(cms, source);
+  holder[CACHE] = { at: Date.now(), map };
+  map.catch(() => {
+    if (holder[CACHE]?.map === map) delete holder[CACHE];
+  });
+  return map;
+}
+async function load(cms, source) {
+  const map = /* @__PURE__ */ new Map();
+  for (let page = 1; ; page++) {
+    const result = await cms.find(source.slug, { depth: 0, sort: "id", limit: 500, page });
+    for (const doc of result.docs) {
+      const from = typeof doc.from === "string" ? normalizePath(doc.from) : null;
+      if (!from) continue;
+      const location = await target(cms, source, doc);
+      if (!location || normalizePath(location) === from) continue;
+      const status = Number(doc.type);
+      map.set(from, {
+        location,
+        status: STATUSES.includes(status) ? status : 301
+      });
+    }
+    if (!result.hasNextPage) break;
+  }
+  return map;
+}
+async function target(cms, source, doc) {
+  if (typeof doc.to === "string" && doc.to.trim()) return doc.to.trim();
+  for (const collection of source.collections) {
+    const ref = doc[targetField(collection)];
+    const id = typeof ref === "object" && ref !== null ? ref.id : ref;
+    if (id === null || id === void 0) continue;
+    const locale = typeof doc.locale === "string" ? doc.locale : null;
+    const page = await cms.findById(collection, id, {
+      depth: 0,
+      ...locale ? { locale } : {}
+    });
+    if (!page || page.status !== void 0 && page.status !== "published") return null;
+    const url = await source.url?.({ collection, doc: page, locale });
+    return typeof url === "string" && url.trim() ? url.trim() : null;
+  }
+  return null;
+}
+
+// src/plugin.ts
+function redirectsPlugin(options = {}) {
+  return (config) => {
+    const slug = options.slug ?? "redirects";
+    const collections = options.collections ?? [];
+    const missing = collections.filter((s) => !config.collections?.some((c) => c.slug === s));
+    if (missing.length > 0)
+      throw new Error(
+        `redirectsPlugin: unknown collection ${missing.map((s) => `"${s}"`).join(", ")}`
+      );
+    if (collections.length > 0 && !options.url)
+      throw new Error(
+        "redirectsPlugin: set `url` to give the address of documents in `collections`"
+      );
+    if (config.collections?.some((c) => c.slug === slug))
+      throw new Error(`redirectsPlugin: there is already a collection "${slug}"; set \`slug\``);
+    const locales = config.localization?.locales ?? [];
+    const auto = options.autoRedirect === false ? [] : options.autoRedirect === true || options.autoRedirect === void 0 ? collections : options.autoRedirect.filter((s) => collections.includes(s));
+    const urlOf = async (cms, collection, id, locale) => {
+      const doc = await cms.findById(collection, id, {
+        depth: 0,
+        ...locale ? { locale } : {}
+      });
+      if (!doc || doc.status !== void 0 && doc.status !== "published") return null;
+      const url = await options.url?.({ collection, doc, locale });
+      return typeof url === "string" && url.trim() ? normalizePath(url) : null;
+    };
+    const localeList = locales.length > 0 ? locales : [null];
+    const source = {
+      slug,
+      collections,
+      url: options.url,
+      cacheTTL: options.cacheTTL ?? 6e4
+    };
+    const targets = collections.map((collection) => {
+      const label = config.collections?.find((c) => c.slug === collection)?.labels?.singular;
+      return {
+        name: targetField(collection),
+        type: "relationship",
+        to: collection,
+        label: label ?? collection
+      };
+    });
+    const redirectFields = [
+      {
+        name: "from",
+        type: "text",
+        required: true,
+        unique: true,
+        label: { en: "From", th: "\u0E08\u0E32\u0E01" },
+        validate: (value) => value === null || value === void 0 || normalizePath(String(value)) !== null ? true : "must be a path like /old-page"
+      },
+      {
+        name: "to",
+        type: "text",
+        label: { en: "To (address)", th: "\u0E44\u0E1B\u0E17\u0E35\u0E48 (\u0E17\u0E35\u0E48\u0E2D\u0E22\u0E39\u0E48)" },
+        validate: (value, { data }) => {
+          const set = [value, ...collections.map((c) => data[targetField(c)])].filter(
+            (v) => v !== null && v !== void 0 && v !== ""
+          );
+          if (set.length === 0)
+            return collections.length > 0 ? "give an address or pick a document" : "give an address, e.g. /new-page or https://example.com";
+          if (set.length > 1) return "give an address or a document, not both";
+          if (typeof value === "string" && value && !/^(\/|https?:\/\/)/.test(value.trim()))
+            return "must start with / or http(s)://";
+          return true;
+        }
+      },
+      ...targets,
+      ...locales.length > 0 && collections.length > 0 ? [
+        {
+          name: "locale",
+          type: "select",
+          options: [...locales],
+          label: { en: "Document locale", th: "\u0E20\u0E32\u0E29\u0E32\u0E02\u0E2D\u0E07\u0E40\u0E2D\u0E01\u0E2A\u0E32\u0E23" }
+        }
+      ] : [],
+      {
+        name: "type",
+        type: "select",
+        options: STATUSES.map(String),
+        defaultValue: "301",
+        required: true,
+        label: { en: "Type", th: "\u0E0A\u0E19\u0E34\u0E14" },
+        position: "sidebar"
+      }
+    ];
+    const clear = ({ cms }) => clearRedirects(cms);
+    const redirects2 = {
+      slug,
+      labels: {
+        singular: { en: "Redirect", th: "\u0E01\u0E32\u0E23\u0E40\u0E1B\u0E25\u0E35\u0E48\u0E22\u0E19\u0E40\u0E2A\u0E49\u0E19\u0E17\u0E32\u0E07" },
+        plural: { en: "Redirects", th: "\u0E01\u0E32\u0E23\u0E40\u0E1B\u0E25\u0E35\u0E48\u0E22\u0E19\u0E40\u0E2A\u0E49\u0E19\u0E17\u0E32\u0E07" }
+      },
+      icon: "link",
+      useAsTitle: "from",
+      editIn: "drawer",
+      admin: { group: "settings" },
+      fields: redirectFields,
+      hooks: {
+        beforeChange: [
+          ({ data }) => typeof data.from === "string" ? { ...data, from: normalizePath(data.from) ?? data.from } : data
+        ],
+        afterChange: [clear],
+        afterDelete: [clear]
+      }
+    };
+    const before = /* @__PURE__ */ new Map();
+    const remember = async ({ data, operation, originalDoc, cms, slug: s }) => {
+      if (operation === "update" && originalDoc?.id !== void 0)
+        before.set(
+          `${s}:${originalDoc.id}`,
+          await Promise.all(localeList.map((l) => urlOf(cms, s, originalDoc.id, l)))
+        );
+      return data;
+    };
+    const redirectOld = async ({ doc, cms, slug: s }) => {
+      clearRedirects(cms);
+      const key = `${s}:${doc.id}`;
+      const old = before.get(key);
+      before.delete(key);
+      if (!old) return;
+      const now = await Promise.all(localeList.map((l) => urlOf(cms, s, doc.id, l)));
+      const done = /* @__PURE__ */ new Set();
+      for (const [i, locale] of localeList.entries()) {
+        const from = old[i];
+        const to = now[i];
+        if (!from || !to || from === to || done.has(from)) continue;
+        done.add(from);
+        await addRedirect(cms, { from, collection: s, id: doc.id, locale, current: to });
+      }
+    };
+    const addRedirect = async (cms, args) => {
+      const loops = await cms.find(slug, { where: { from: { equals: args.current } }, limit: 100 });
+      for (const loop of loops.docs) await cms.delete(slug, loop.id);
+      const data = {
+        from: args.from,
+        to: null,
+        [targetField(args.collection)]: args.id,
+        ...locales.length > 0 ? { locale: args.locale } : {},
+        type: "301"
+      };
+      const existing = await cms.find(slug, { where: { from: { equals: args.from } }, limit: 1 });
+      if (existing.docs[0]) await cms.update(slug, existing.docs[0].id, data);
+      else await cms.create(slug, data);
+    };
+    const withAuto = (c) => {
+      if (!collections.includes(c.slug)) return c;
+      const hooks = { ...c.hooks };
+      if (auto.includes(c.slug)) {
+        hooks.beforeChange = [...hooks.beforeChange ?? [], remember];
+        hooks.afterChange = [...hooks.afterChange ?? [], redirectOld];
+      } else {
+        hooks.afterChange = [...hooks.afterChange ?? [], clear];
+      }
+      hooks.afterDelete = [...hooks.afterDelete ?? [], clear];
+      return { ...c, hooks };
+    };
+    const endpoint = {
+      path: "/resolve-redirect",
+      method: "get",
+      // Lets `resolveRedirect(cms)` find these options from the resolved config.
+      handler: Object.assign(
+        async ({ url, cms }) => {
+          const path = url.searchParams.get("path");
+          if (!path)
+            return Response.json({ errors: [{ message: "path is required" }] }, { status: 400 });
+          const redirect = await resolveRedirect(cms, path);
+          if (!redirect)
+            return Response.json({ errors: [{ message: "No redirect" }] }, { status: 404 });
+          return Response.json(redirect, { headers: { "cache-control": "public, max-age=60" } });
+        },
+        { [REDIRECTS_SOURCE]: source }
+      )
+    };
+    return {
+      ...config,
+      collections: [...(config.collections ?? []).map(withAuto), redirects2],
+      endpoints: [...config.endpoints ?? [], endpoint]
+    };
+  };
+}
+export {
+  STATUSES,
+  clearRedirects,
+  normalizePath,
+  redirectsPlugin,
+  resolveRedirect
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@easy-cms/plugin-redirects",
+  "version": "0.18.0",
+  "description": "Redirects for Easy CMS: 301s managed in the admin, automatic redirects when a page's address changes",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@easy-cms/core": "^0.18.0"
+  },
+  "devDependencies": {
+    "@easy-cms/core": "^0.18.0",
+    "@easy-cms/db-sqlite": "^0.18.0"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maritonx/easy-cms.git",
+    "directory": "packages/plugin-redirects"
+  },
+  "keywords": [
+    "easy-cms",
+    "easy-cms-plugin",
+    "redirects",
+    "301",
+    "seo"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}