@jakubmazanec/template 1.0.0-a3e1bca

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@jakubmazanec/template",
+  "version": "1.0.0-a3e1bca",
+  "description": "TypeScript-first library for working with templates using EJS and Zod.",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:jakubmazanec/js-tools.git",
+    "directory": "packages/template"
+  },
+  "license": "LGPL-3.0-only",
+  "author": "Jakub Mazanec <jakub@mazanec.dev>",
+  "sideEffects": false,
+  "type": "module",
+  "exports": "./dist/main.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "swc src -d dist && tsc",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "document": "typedoc --options typedoc.config.cjs",
+    "format": "prettier . --write --ignore-unknown --ignore-path ../../.prettierignore",
+    "lint": "eslint .",
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
+    "typecheck": "tsc --project tsconfig.typecheck.json"
+  },
+  "dependencies": {
+    "@jakubmazanec/error": "2.0.0-a3e1bca",
+    "ejs": "^3.1.9",
+    "fs-extra": "^11.1.1",
+    "gray-matter": "^4.0.3",
+    "lodash.omit": "^4.5.0",
+    "prettier": "^2.8.7",
+    "yaml": "^2.2.1",
+    "zod": "^3.21.4"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@types/ejs": "^3.1.2",
+    "@types/fs-extra": "^11.0.1",
+    "@types/lodash.omit": "^4.5.7",
+    "@types/node": "^16.18.3"
+  },
+  "packageManager": "npm@8.19.4",
+  "engines": {
+    "node": ">=16.20.0"
+  }
+}

package/src/Template.ts

@@ -0,0 +1,266 @@
+import ejs from 'ejs';
+import fs from 'fs-extra';
+import matter from 'gray-matter';
+import omit from 'lodash.omit';
+import prettier from 'prettier';
+import yaml from 'yaml';
+import {type z, type AnyZodObject} from 'zod';
+
+import {NO_INFERRED_PARSER_REGEXP} from './constants.js';
+import {TemplateError} from './TemplateError.js';
+import {
+  templateAttributesSchema,
+  type TemplateAttributes,
+  type TemplateFunction,
+  type TemplateRender,
+  type TemplateRenders,
+} from './types.js';
+
+export type TemplateOptions<
+  A extends AnyZodObject | undefined = undefined,
+  D extends AnyZodObject | undefined = undefined,
+> = {
+  /** Template content. */
+  content: string;
+
+  /** Template attributes.  */
+  attributes: A extends undefined
+    ? TemplateAttributes
+    : TemplateAttributes & z.infer<NonNullable<A>>;
+
+  /** Zod schema for custom template attributes. */
+  attributesSchema?: A | undefined;
+
+  /** Zod schema for template data. */
+  dataSchema?: D | undefined;
+};
+
+export type TemplateReadOptions<
+  A extends AnyZodObject | undefined = undefined,
+  D extends AnyZodObject | undefined = undefined,
+> = {
+  /** Zod schema for custom template attributes. */
+  attributesSchema?: A | undefined;
+
+  /** Zod schema for template data. */
+  dataSchema?: D | undefined;
+};
+
+export type TemplateReadAndRenderOptions<
+  A extends AnyZodObject | undefined = undefined,
+  D extends AnyZodObject | undefined = undefined,
+> = {
+  /** Prettier options.  */
+  prettierOptions?: prettier.Options | undefined;
+
+  /** Disable formatting the rendered template using Prettier.  */
+  disablePrettier?: boolean | undefined;
+
+  /** Zod schema for custom template attributes. */
+  attributesSchema?: A | undefined;
+
+  /** Zod schema for template data. */
+  dataSchema?: D | undefined;
+};
+
+export type TemplateRenderOptions = {
+  /** Prettier options.  */
+  prettierOptions?: prettier.Options | undefined;
+
+  /** Disable formatting the rendered template using Prettier.  */
+  disablePrettier?: boolean | undefined;
+};
+
+/**
+ * The `Template` object stores all information about a template and has methods for reading and rendering.
+ *
+ * ```TypeScript
+ * let template = new Template({
+ *   content: '<%- value %>',
+ *   attributes: {
+ *     to: 'value.txt',
+ *   },
+ *   dataSchema: z.object({value: z.number()}),
+ * });
+ *
+ * console.log(await template.render({value: 42})); // ->  [{attributes: {to: 'value.txt'}, data: {value: 42}, content: '42'}]
+ * ```
+ *
+ * @typeParam A A Zod schema type used to define the custom template attributes type.
+ * @typeParam D A Zod schema type used to define the template datatype.
+ */
+export class Template<
+  A extends AnyZodObject | undefined = undefined,
+  D extends AnyZodObject | undefined = undefined,
+> {
+  /** Template content. Templates are written in [EJS](https://ejs.co/). */
+  readonly content: string;
+
+  /** Template attributes. These control how the template is rendered. Some attributes can be written in [EJS](https://ejs.co/) and are rendered before the template content is rendered. It is expected that attribute `if` renders to a string that can be parsed as YAML value; if that value is `false`, the rendering is cancelled. Attribute `to` is also rendered and it represents the path of file the resulting template render is supposed to be written into (by the user). Attribute `variables` is an object that is merged with the data object before rendering. If attribute `variables` is an array of objects, that leads to multiple renders, each with different variables object merged with the data. Each variable that is a string is also rendered. */
+  readonly attributes: A extends undefined
+    ? TemplateAttributes
+    : TemplateAttributes & z.infer<NonNullable<A>>;
+
+  /** Template function. */
+  private readonly fn: TemplateFunction;
+
+  /** Zod schema for custom template attributes. */
+  readonly attributesSchema: A extends AnyZodObject ? A : null;
+
+  /** Zod schema for template data. */
+  readonly dataSchema: D extends AnyZodObject ? D : null;
+
+  constructor({content, attributes, attributesSchema, dataSchema}: TemplateOptions<A, D>) {
+    this.content = content;
+    this.attributes = attributes;
+    this.fn = ejs.compile(this.content);
+
+    if (attributesSchema) {
+      this.attributesSchema = attributesSchema as A extends AnyZodObject ? A : null;
+    } else {
+      this.attributesSchema = null as A extends AnyZodObject ? A : null;
+    }
+
+    if (dataSchema) {
+      this.dataSchema = dataSchema as D extends AnyZodObject ? D : null;
+    } else {
+      this.dataSchema = null as D extends AnyZodObject ? D : null;
+    }
+  }
+
+  /**
+   * Reads a template from a file.
+   *
+   * @param templateFilePath Path to the template file.
+   */
+  static async read<
+    A extends AnyZodObject | undefined = undefined,
+    D extends AnyZodObject | undefined = undefined,
+  >(templateFilePath: string, options?: TemplateReadOptions<A, D>): Promise<Template<A, D>> {
+    let {data: attributes, content} = matter(await fs.readFile(templateFilePath, 'utf8'));
+    let attributesSchema = options?.attributesSchema
+      ? templateAttributesSchema.merge(options.attributesSchema)
+      : templateAttributesSchema;
+    let attributesParseResult = attributesSchema.safeParse(attributes);
+
+    if (!attributesParseResult.success) {
+      throw new TemplateError('INVALID_ATTRIBUTES', {
+        cause: attributesParseResult.error,
+        data: {
+          path: templateFilePath,
+          zodIssues: attributesParseResult.error.issues,
+        },
+      });
+    }
+
+    return new this({
+      attributes,
+      content,
+      attributesSchema: options?.attributesSchema,
+      dataSchema: options?.dataSchema,
+    } as TemplateOptions<A, D>);
+  }
+
+  /**
+   * Reads a template from a file and then renders it.
+   *
+   * @param templateFilePath Path to the template file.
+   * @param data Data used for rendering the template.
+   * @param options Options object.
+   * @return Template renders.
+   */
+  static async readAndRender<
+    A extends AnyZodObject | undefined = undefined,
+    D extends AnyZodObject | undefined = undefined,
+  >(
+    templateFilePath: string,
+    data: D extends undefined ? null : z.infer<NonNullable<D>>,
+    options?: TemplateReadAndRenderOptions<A, D>,
+  ) {
+    let template = await Template.read<A, D>(templateFilePath, {
+      attributesSchema: options?.attributesSchema,
+      dataSchema: options?.dataSchema,
+    });
+
+    return template.render(data, {
+      prettierOptions: options?.prettierOptions,
+      disablePrettier: options?.disablePrettier,
+    });
+  }
+
+  /**
+   * Renders the template using data.
+   *
+   * @param data Data used for rendering the template.
+   * @param options Options object.
+   * @return Template renders.
+   */
+  async render(
+    data: D extends undefined ? null : z.infer<NonNullable<D>>,
+    options?: TemplateRenderOptions,
+  ): Promise<TemplateRenders<A, D>> {
+    let renders: TemplateRenders<A, D> = [];
+
+    for (let variables of Array.isArray(this.attributes.variables)
+      ? this.attributes.variables
+      : [this.attributes.variables]) {
+      let renderedAttributes = omit(this.attributes, ['if']);
+      let renderedVariables = variables;
+
+      if (renderedVariables) {
+        for (let [variableName, variableValue] of Object.entries(renderedVariables)) {
+          if (typeof variableValue === 'string') {
+            renderedVariables[variableName] = ejs.render(variableValue, {...data});
+          } else {
+            renderedVariables[variableName] = variableValue;
+          }
+        }
+
+        renderedAttributes.variables = renderedVariables;
+      }
+
+      let dataWithAttributes = {...data, attributes: renderedAttributes};
+
+      if (this.attributes.if) {
+        let renderedIf = ejs.render(this.attributes.if, dataWithAttributes);
+        let parsedIf = yaml.parse(renderedIf) as unknown;
+
+        if (parsedIf === false) {
+          continue;
+        }
+      }
+
+      renderedAttributes.to = ejs.render(renderedAttributes.to, dataWithAttributes);
+      dataWithAttributes.attributes = renderedAttributes;
+
+      let content;
+
+      try {
+        content = this.fn(dataWithAttributes);
+      } catch (error: unknown) {
+        throw new TemplateError('FAILED_RENDER', {cause: error});
+      }
+
+      if (!options?.disablePrettier) {
+        try {
+          content = prettier.format(content, {
+            ...options?.prettierOptions,
+            filepath: renderedAttributes.to,
+          });
+        } catch (error: unknown) {
+          if (!NO_INFERRED_PARSER_REGEXP.test((error as Error).message)) {
+            throw new TemplateError('FAILED_FORMAT', {cause: error});
+          }
+        }
+      }
+
+      renders.push({
+        attributes: renderedAttributes,
+        data: data ?? null,
+        content,
+      } as TemplateRender<A, D>);
+    }
+
+    return renders;
+  }
+}

package/src/TemplateError.ts

@@ -0,0 +1,21 @@
+import {createCustomErrorWithData} from '@jakubmazanec/error';
+import {type ZodIssue} from 'zod';
+
+import {type Template} from './Template.js';
+
+/**
+ * A subclass of `Error` that indicates a template  failure.
+ */
+export const TemplateError = createCustomErrorWithData(
+  'TemplateError',
+  {
+    INVALID_ATTRIBUTES: 'Invalid template attributes.',
+    FAILED_FORMAT: 'Template render formatting has failed.',
+    FAILED_RENDER: 'Rendering has failed.',
+  },
+  class TemplateErrorData {
+    template?: Template;
+    path?: string;
+    zodIssues?: ZodIssue[];
+  },
+);

package/src/constants.ts

@@ -0,0 +1 @@
+export const NO_INFERRED_PARSER_REGEXP = /parser.*inferred/i;

package/src/main.ts

@@ -0,0 +1,3 @@
+export * from './Template.js';
+export * from './TemplateError.js';
+export * from './types.js';

package/src/types/TemplateAttributes.ts

@@ -0,0 +1,19 @@
+import {z} from 'zod';
+
+import {templateVariablesSchema} from './TemplateVariables.js';
+
+/**
+ * Zod schema for {@linkcode TemplateAttributes}.
+ */
+export const templateAttributesSchema = z
+  .object({
+    to: z.string(),
+    if: z.string().optional(),
+    variables: templateVariablesSchema.optional(),
+  })
+  .strict();
+
+/**
+ * Type representing template attributes.
+ */
+export type TemplateAttributes = z.infer<typeof templateAttributesSchema>;

package/src/types/TemplateContent.ts

@@ -0,0 +1,4 @@
+/**
+ * Type representing a template content.
+ */
+export type TemplateContent = string;

package/src/types/TemplateFunction.ts

@@ -0,0 +1,4 @@
+/**
+ * Type representing a template function that takes data and returns rendered string.
+ */
+export type TemplateFunction = (data?: Record<string, unknown>) => string;

package/src/types/TemplateRender.ts

@@ -0,0 +1,26 @@
+import {type z} from 'zod';
+
+import {type TemplateAttributes} from './TemplateAttributes.js';
+
+/**
+ * An object type representing the result of a template render.
+ *
+ * @typeParam A Type of Zod schema used to validate the custom template attributes.
+ * @typeParam D Type of Zod schema used to define the type of template data.
+ */
+export type TemplateRender<
+  A extends z.AnyZodObject | undefined = undefined,
+  D extends z.AnyZodObject | undefined = undefined,
+> = {
+  /** Rendered template attributes. They created from the `to` and `variables` attributes, and from all of the custom template attributes.
+   */
+  attributes: A extends undefined
+    ? Omit<TemplateAttributes, 'if'>
+    : Omit<TemplateAttributes, 'if'> & z.infer<NonNullable<A>>;
+
+  /** Data used to render the template. */
+  data: D extends undefined ? null : z.infer<NonNullable<D>>;
+
+  /** Rendered template content. */
+  content: string;
+};

package/src/types/TemplateRenders.ts

@@ -0,0 +1,8 @@
+import {type z} from 'zod';
+
+import {type TemplateRender} from './TemplateRender.js';
+
+export type TemplateRenders<
+  A extends z.AnyZodObject | undefined = undefined,
+  D extends z.AnyZodObject | undefined = undefined,
+> = Array<TemplateRender<A, D>>;

package/src/types/TemplateVariables.ts

@@ -0,0 +1,14 @@
+import * as z from 'zod';
+
+/**
+ * Zod schema for {@linkcode TemplateAttributesVariables}.
+ */
+export const templateVariablesSchema = z.union([
+  z.record(z.unknown()),
+  z.array(z.record(z.unknown())),
+]);
+
+/**
+ * Type of `variables`` property of {@linkcode TemplateAttributes}.
+ */
+export type TemplateAttributesVariables = z.infer<typeof templateVariablesSchema>;

package/src/types.ts

@@ -0,0 +1,5 @@
+export * from './types/TemplateAttributes.js';
+export * from './types/TemplateVariables.js';
+export * from './types/TemplateFunction.js';
+export * from './types/TemplateRender.js';
+export * from './types/TemplateRenders.js';