@docusaurus/plugin-client-redirects 2.0.0-beta.17 → 2.0.0-beta.18

package/lib/collectRedirects.js

@@ -106,9 +106,7 @@ function createRedirectsOptionRedirects(redirectsOption) {
 // Create redirects from the "createRedirects" fn provided by the user
 function createCreateRedirectsOptionRedirects(paths, createRedirects) {
     function createPathRedirects(path) {
-        const fromsMixed = createRedirects
-            ? createRedirects(path) || []
-            : [];
+        const fromsMixed = createRedirects?.(path) ?? [];
         const froms = typeof fromsMixed === 'string' ? [fromsMixed] : fromsMixed;
         return froms.map((from) => ({
             from,

package/lib/createRedirectPageContent.d.ts

@@ -4,8 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-declare type CreateRedirectPageOptions = {
+export default function createRedirectPageContent({ toUrl, }: {
     toUrl: string;
-};
-export default function createRedirectPageContent({ toUrl, }: CreateRedirectPageOptions): string;
-export {};
+}): string;

package/lib/index.d.ts

@@ -6,4 +6,5 @@
  */
 import type { LoadContext, Plugin } from '@docusaurus/types';
 import type { PluginOptions } from '@docusaurus/plugin-client-redirects';
-export default function pluginClientRedirectsPages(context: LoadContext, opts: PluginOptions): Plugin<unknown>;
+export default function pluginClientRedirectsPages(context: LoadContext, options: PluginOptions): Plugin<unknown>;
+export { validateOptions } from './options';

package/lib/index.js

@@ -6,14 +6,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOptions = void 0;
 const tslib_1 = require("tslib");
-const normalizePluginOptions_1 = tslib_1.__importDefault(require("./normalizePluginOptions"));
 const collectRedirects_1 = tslib_1.__importDefault(require("./collectRedirects"));
 const writeRedirectFiles_1 = tslib_1.__importStar(require("./writeRedirectFiles"));
 const utils_1 = require("@docusaurus/utils");
-function pluginClientRedirectsPages(context, opts) {
+function pluginClientRedirectsPages(context, options) {
     const { trailingSlash } = context.siteConfig;
-    const options = (0, normalizePluginOptions_1.default)(opts);
     return {
         name: 'docusaurus-plugin-client-redirects',
         async postBuild(props) {
@@ -31,3 +30,5 @@ function pluginClientRedirectsPages(context, opts) {
     };
 }
 exports.default = pluginClientRedirectsPages;
+var options_1 = require("./options");
+Object.defineProperty(exports, "validateOptions", { enumerable: true, get: function () { return options_1.validateOptions; } });

package/lib/options.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { PluginOptions, Options } from '@docusaurus/plugin-client-redirects';
+import type { OptionValidationContext } from '@docusaurus/types';
+export declare const DEFAULT_OPTIONS: Partial<PluginOptions>;
+export declare function validateOptions({ validate, options: userOptions, }: OptionValidationContext<Options, PluginOptions>): PluginOptions;

package/lib/options.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateOptions = exports.DEFAULT_OPTIONS = void 0;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+exports.DEFAULT_OPTIONS = {
+    fromExtensions: [],
+    toExtensions: [],
+    redirects: [],
+};
+const RedirectPluginOptionValidation = utils_validation_1.Joi.object({
+    to: utils_validation_1.PathnameSchema.required(),
+    from: utils_validation_1.Joi.alternatives().try(utils_validation_1.PathnameSchema.required(), utils_validation_1.Joi.array().items(utils_validation_1.PathnameSchema.required())),
+});
+const isString = utils_validation_1.Joi.string().required().not(null);
+const UserOptionsSchema = utils_validation_1.Joi.object({
+    fromExtensions: utils_validation_1.Joi.array()
+        .items(isString)
+        .default(exports.DEFAULT_OPTIONS.fromExtensions),
+    toExtensions: utils_validation_1.Joi.array()
+        .items(isString)
+        .default(exports.DEFAULT_OPTIONS.toExtensions),
+    redirects: utils_validation_1.Joi.array()
+        .items(RedirectPluginOptionValidation)
+        .default(exports.DEFAULT_OPTIONS.redirects),
+    createRedirects: utils_validation_1.Joi.function().maxArity(1),
+}).default(exports.DEFAULT_OPTIONS);
+function validateOptions({ validate, options: userOptions, }) {
+    return validate(UserOptionsSchema, userOptions);
+}
+exports.validateOptions = validateOptions;

package/lib/types.d.ts

@@ -6,11 +6,21 @@
  */
 import type { Props } from '@docusaurus/types';
 import type { PluginOptions } from '@docusaurus/plugin-client-redirects';
+/**
+ * The minimal infos the plugin needs to work
+ */
 export declare type PluginContext = Pick<Props, 'outDir' | 'baseUrl'> & {
     options: PluginOptions;
     relativeRoutesPaths: string[];
 };
+/**
+ * In-memory representation of redirects we want: easier to test
+ * /!\ easy to be confused: "from" is the new page we should create,
+ * that redirects to "to": the existing Docusaurus page
+ */
 export declare type RedirectMetadata = {
+    /** Pathname of the new page we should create */
     from: string;
+    /** Pathname of an existing Docusaurus page */
     to: string;
 };

package/lib/writeRedirectFiles.js

@@ -69,8 +69,7 @@ async function writeRedirectFile(file) {
         if (await fs_extra_1.default.pathExists(file.fileAbsolutePath)) {
             throw new Error('The redirect plugin is not supposed to override existing files.');
         }
-        await fs_extra_1.default.ensureDir(path_1.default.dirname(file.fileAbsolutePath));
-        await fs_extra_1.default.writeFile(file.fileAbsolutePath, file.fileContent, 
+        await fs_extra_1.default.outputFile(file.fileAbsolutePath, file.fileContent, 
         // Hard security to prevent file overrides
         // See https://stackoverflow.com/a/34187712/82609
         { flag: 'wx' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-client-redirects",
-  "version": "2.0.0-beta.17",
+  "version": "2.0.0-beta.18",
   "description": "Client redirects plugin for Docusaurus.",
   "main": "lib/index.js",
   "types": "src/plugin-client-redirects.d.ts",
@@ -18,18 +18,18 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.17",
-    "@docusaurus/logger": "2.0.0-beta.17",
-    "@docusaurus/utils": "2.0.0-beta.17",
-    "@docusaurus/utils-common": "2.0.0-beta.17",
-    "@docusaurus/utils-validation": "2.0.0-beta.17",
+    "@docusaurus/core": "2.0.0-beta.18",
+    "@docusaurus/logger": "2.0.0-beta.18",
+    "@docusaurus/utils": "2.0.0-beta.18",
+    "@docusaurus/utils-common": "2.0.0-beta.18",
+    "@docusaurus/utils-validation": "2.0.0-beta.18",
     "eta": "^1.12.3",
     "fs-extra": "^10.0.1",
     "lodash": "^4.17.21",
     "tslib": "^2.3.1"
   },
   "devDependencies": {
-    "@docusaurus/types": "2.0.0-beta.17"
+    "@docusaurus/types": "2.0.0-beta.18"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
@@ -38,5 +38,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "0032c0b0480083227af2e1b4da2d3ee6ce992403"
+  "gitHead": "1a945d06993d53376e61bed2c942799fe07dc336"
 }

package/src/collectRedirects.ts

@@ -166,9 +166,7 @@ function createCreateRedirectsOptionRedirects(
   createRedirects: PluginOptions['createRedirects'],
 ): RedirectMetadata[] {
   function createPathRedirects(path: string): RedirectMetadata[] {
-    const fromsMixed: string | string[] = createRedirects
-      ? createRedirects(path) || []
-      : [];
+    const fromsMixed: string | string[] = createRedirects?.(path) ?? [];
 
     const froms: string[] =
       typeof fromsMixed === 'string' ? [fromsMixed] : fromsMixed;

package/src/createRedirectPageContent.ts

@@ -9,22 +9,20 @@ import * as eta from 'eta';
 import redirectPageTemplate from './templates/redirectPage.template.html';
 import _ from 'lodash';
 
-type CreateRedirectPageOptions = {
-  toUrl: string;
-};
-
 const getCompiledRedirectPageTemplate = _.memoize(() =>
   eta.compile(redirectPageTemplate.trim()),
 );
 
-function renderRedirectPageTemplate(data: Record<string, unknown>) {
+function renderRedirectPageTemplate(data: {toUrl: string}) {
   const compiled = getCompiledRedirectPageTemplate();
   return compiled(data, eta.defaultConfig);
 }
 
 export default function createRedirectPageContent({
   toUrl,
-}: CreateRedirectPageOptions): string {
+}: {
+  toUrl: string;
+}): string {
   return renderRedirectPageTemplate({
     toUrl: encodeURI(toUrl),
   });

package/src/index.ts

@@ -5,11 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {LoadContext, Plugin, Props} from '@docusaurus/types';
+import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {PluginContext, RedirectMetadata} from './types';
 import type {PluginOptions} from '@docusaurus/plugin-client-redirects';
 
-import normalizePluginOptions from './normalizePluginOptions';
 import collectRedirects from './collectRedirects';
 import writeRedirectFiles, {
   toRedirectFilesMetadata,
@@ -19,15 +18,13 @@ import {removePrefix, addLeadingSlash} from '@docusaurus/utils';
 
 export default function pluginClientRedirectsPages(
   context: LoadContext,
-  opts: PluginOptions,
+  options: PluginOptions,
 ): Plugin<unknown> {
   const {trailingSlash} = context.siteConfig;
 
-  const options = normalizePluginOptions(opts);
-
   return {
     name: 'docusaurus-plugin-client-redirects',
-    async postBuild(props: Props) {
+    async postBuild(props) {
       const pluginContext: PluginContext = {
         relativeRoutesPaths: props.routesPaths.map(
           (path) => `${addLeadingSlash(removePrefix(path, props.baseUrl))}`,
@@ -53,3 +50,5 @@ export default function pluginClientRedirectsPages(
     },
   };
 }
+
+export {validateOptions} from './options';

package/src/options.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {
+  PluginOptions,
+  Options,
+  RedirectOption,
+} from '@docusaurus/plugin-client-redirects';
+import type {OptionValidationContext} from '@docusaurus/types';
+import {Joi, PathnameSchema} from '@docusaurus/utils-validation';
+
+export const DEFAULT_OPTIONS: Partial<PluginOptions> = {
+  fromExtensions: [],
+  toExtensions: [],
+  redirects: [],
+};
+
+const RedirectPluginOptionValidation = Joi.object<RedirectOption>({
+  to: PathnameSchema.required(),
+  from: Joi.alternatives().try(
+    PathnameSchema.required(),
+    Joi.array().items(PathnameSchema.required()),
+  ),
+});
+
+const isString = Joi.string().required().not(null);
+
+const UserOptionsSchema = Joi.object<PluginOptions>({
+  fromExtensions: Joi.array()
+    .items(isString)
+    .default(DEFAULT_OPTIONS.fromExtensions),
+  toExtensions: Joi.array()
+    .items(isString)
+    .default(DEFAULT_OPTIONS.toExtensions),
+  redirects: Joi.array()
+    .items(RedirectPluginOptionValidation)
+    .default(DEFAULT_OPTIONS.redirects),
+  createRedirects: Joi.function().maxArity(1),
+}).default(DEFAULT_OPTIONS);
+
+export function validateOptions({
+  validate,
+  options: userOptions,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  return validate(UserOptionsSchema, userOptions);
+}

package/src/plugin-client-redirects.d.ts

@@ -10,18 +10,23 @@ export type RedirectOption = {
   from: string | string[];
 };
 
-// For a given existing route path,
-// return all the paths from which we should redirect from
-export type CreateRedirectsFnOption = (
-  path: string,
-) => string[] | string | null | undefined;
-
 export type PluginOptions = {
+  /** Plugin ID. */
   id: string;
+  /** The extensions to be removed from the route after redirecting. */
   fromExtensions: string[];
+  /** The extensions to be appended to the route after redirecting. */
   toExtensions: string[];
+  /** The list of redirect rules, each one with multiple `from`s → one `to`. */
   redirects: RedirectOption[];
-  createRedirects?: CreateRedirectsFnOption;
+  /**
+   * A callback to create a redirect rule.
+   * @returns All the paths from which we should redirect to `path`
+   */
+  createRedirects?: (
+    /** An existing Docusaurus route path */
+    path: string,
+  ) => string[] | string | null | undefined;
 };
 
 export type Options = Partial<PluginOptions>;

package/src/types.ts

@@ -8,16 +8,22 @@
 import type {Props} from '@docusaurus/types';
 import type {PluginOptions} from '@docusaurus/plugin-client-redirects';
 
-// The minimal infos the plugin needs to work
+/**
+ * The minimal infos the plugin needs to work
+ */
 export type PluginContext = Pick<Props, 'outDir' | 'baseUrl'> & {
   options: PluginOptions;
   relativeRoutesPaths: string[];
 };
 
-// In-memory representation of redirects we want: easier to test
-// /!\ easy to be confused: "from" is the new page we should create,
-// that redirects to "to": the existing Docusaurus page
+/**
+ * In-memory representation of redirects we want: easier to test
+ * /!\ easy to be confused: "from" is the new page we should create,
+ * that redirects to "to": the existing Docusaurus page
+ */
 export type RedirectMetadata = {
-  from: string; // pathname
-  to: string; // pathname
+  /** Pathname of the new page we should create */
+  from: string;
+  /** Pathname of an existing Docusaurus page */
+  to: string;
 };

package/src/writeRedirectFiles.ts

@@ -92,8 +92,7 @@ export async function writeRedirectFile(
         'The redirect plugin is not supposed to override existing files.',
       );
     }
-    await fs.ensureDir(path.dirname(file.fileAbsolutePath));
-    await fs.writeFile(
+    await fs.outputFile(
       file.fileAbsolutePath,
       file.fileContent,
       // Hard security to prevent file overrides

package/lib/normalizePluginOptions.d.ts

@@ -1,9 +0,0 @@
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-import type { PluginOptions, Options as UserPluginOptions } from '@docusaurus/plugin-client-redirects';
-export declare const DefaultPluginOptions: PluginOptions;
-export default function normalizePluginOptions(userPluginOptions?: UserPluginOptions): PluginOptions;

package/lib/normalizePluginOptions.js

@@ -1,44 +0,0 @@
-"use strict";
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultPluginOptions = void 0;
-const utils_validation_1 = require("@docusaurus/utils-validation");
-const utils_1 = require("@docusaurus/utils");
-exports.DefaultPluginOptions = {
-    id: utils_1.DEFAULT_PLUGIN_ID,
-    fromExtensions: [],
-    toExtensions: [],
-    redirects: [],
-};
-const RedirectPluginOptionValidation = utils_validation_1.Joi.object({
-    to: utils_validation_1.PathnameSchema.required(),
-    from: utils_validation_1.Joi.alternatives().try(utils_validation_1.PathnameSchema.required(), utils_validation_1.Joi.array().items(utils_validation_1.PathnameSchema.required())),
-});
-const isString = utils_validation_1.Joi.string().required().not(null);
-const UserOptionsSchema = utils_validation_1.Joi.object({
-    id: utils_validation_1.Joi.string().optional(),
-    fromExtensions: utils_validation_1.Joi.array().items(isString),
-    toExtensions: utils_validation_1.Joi.array().items(isString),
-    redirects: utils_validation_1.Joi.array().items(RedirectPluginOptionValidation),
-    createRedirects: utils_validation_1.Joi.function().arity(1),
-});
-function validateUserOptions(userOptions) {
-    const { error } = UserOptionsSchema.validate(userOptions, {
-        abortEarly: true,
-        allowUnknown: false,
-    });
-    if (error) {
-        throw new Error(`Invalid @docusaurus/plugin-client-redirects options: ${error.message}
-  ${JSON.stringify(userOptions, null, 2)}`);
-    }
-}
-function normalizePluginOptions(userPluginOptions = {}) {
-    validateUserOptions(userPluginOptions);
-    return { ...exports.DefaultPluginOptions, ...userPluginOptions };
-}
-exports.default = normalizePluginOptions;

package/src/normalizePluginOptions.ts

@@ -1,59 +0,0 @@
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-import type {
-  PluginOptions,
-  Options as UserPluginOptions,
-  RedirectOption,
-} from '@docusaurus/plugin-client-redirects';
-import {Joi, PathnameSchema} from '@docusaurus/utils-validation';
-import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
-
-export const DefaultPluginOptions: PluginOptions = {
-  id: DEFAULT_PLUGIN_ID, // TODO temporary
-  fromExtensions: [],
-  toExtensions: [],
-  redirects: [],
-};
-
-const RedirectPluginOptionValidation = Joi.object<RedirectOption>({
-  to: PathnameSchema.required(),
-  from: Joi.alternatives().try(
-    PathnameSchema.required(),
-    Joi.array().items(PathnameSchema.required()),
-  ),
-});
-
-const isString = Joi.string().required().not(null);
-
-const UserOptionsSchema = Joi.object<UserPluginOptions>({
-  id: Joi.string().optional(), // TODO remove once validation  migrated to new system
-  fromExtensions: Joi.array().items(isString),
-  toExtensions: Joi.array().items(isString),
-  redirects: Joi.array().items(RedirectPluginOptionValidation),
-  createRedirects: Joi.function().arity(1),
-});
-
-function validateUserOptions(userOptions: UserPluginOptions) {
-  const {error} = UserOptionsSchema.validate(userOptions, {
-    abortEarly: true,
-    allowUnknown: false,
-  });
-  if (error) {
-    throw new Error(
-      `Invalid @docusaurus/plugin-client-redirects options: ${error.message}
-  ${JSON.stringify(userOptions, null, 2)}`,
-    );
-  }
-}
-
-export default function normalizePluginOptions(
-  userPluginOptions: UserPluginOptions = {},
-): PluginOptions {
-  validateUserOptions(userPluginOptions);
-  return {...DefaultPluginOptions, ...userPluginOptions};
-}