@jakubmazanec/template 1.0.3 → 1.1.0-next.5d8abeb

package/README.md

@@ -28,6 +28,7 @@ Write templates using [EJS](https://ejs.co/) with YAML front matter:
 
 ```
 ---
+extends: './base.ejs'
 to: <%- attributes.variables.path %>
 if: <%- attributes.variables.enabled %>
 variables:
@@ -90,6 +91,11 @@ Because `variables` is an array, we can expect two renders; but because one of t
 `enabled` is used for rendering the value of `if` attribute and is set to `false` in the second
 case, only one render is actually returned.
 
+You can extend another template using `extends` attribute that represents path to the template to
+extend, relative to the current template. The extended template is read using the same options
+object. The current template attributes are recursively merged with the extended template
+attributes. If the current template has no content, the content from the extended template is used.
+
 ## Documentation
 
 See [API reference](./docs) for auto-generated documentation.

package/dist/Template.d.ts

@@ -67,7 +67,7 @@ export declare class Template<A extends AnyZodObject | undefined = undefined, D
     readonly attributesSchema: A extends AnyZodObject ? A : null;
     /** Zod schema for template data. */
     readonly dataSchema: D extends AnyZodObject ? D : null;
-    constructor({ path, content, attributes, attributesSchema, dataSchema }: TemplateOptions<A, D>);
+    constructor({ path: templatePath, content, attributes, attributesSchema, dataSchema, }: TemplateOptions<A, D>);
     /**
      * Reads a template from a file.
      *

package/dist/Template.js

@@ -1,7 +1,9 @@
 import ejs from 'ejs';
 import fs from 'fs-extra';
 import matter from 'gray-matter';
+import merge from 'lodash.merge';
 import omit from 'lodash.omit';
+import path from 'node:path';
 import prettier from 'prettier';
 import yaml from 'yaml';
 import { NO_INFERRED_PARSER_REGEXP } from './constants.js';
@@ -31,9 +33,9 @@ import { TemplateError } from './TemplateError.js';
     /** Template function. */ fn;
     /** Zod schema for custom template attributes. */ attributesSchema;
     /** Zod schema for template data. */ dataSchema;
-    constructor({ path, content, attributes, attributesSchema, dataSchema }){
-        if (path) {
-            this.path = path;
+    constructor({ path: templatePath, content, attributes, attributesSchema, dataSchema }){
+        if (templatePath) {
+            this.path = templatePath;
         }
         this.content = content;
         this.attributes = attributes;
@@ -54,9 +56,19 @@ import { TemplateError } from './TemplateError.js';
    *
    * @param templatePath Path to the template file.
    */ static async read(templatePath, options) {
-        let { data: attributes, content } = matter(await fs.readFile(templatePath, 'utf8'));
+        let { data: rawAttributes, content } = matter(await fs.readFile(templatePath, 'utf8'));
+        // extending another template
+        if (typeof rawAttributes.extends === 'string' && rawAttributes.extends) {
+            let extendedTemplate = await Template.read(path.join(path.dirname(templatePath), rawAttributes.extends), options); // you can point to any template, but it will be parsed with the same options, including attribute or data schema
+            // attributes are recursively merged
+            rawAttributes = merge(extendedTemplate.attributes, rawAttributes);
+            // if content is empty, use content from the extended template
+            if (!content.trim()) {
+                content = extendedTemplate.content;
+            }
+        }
         let attributesSchema = options?.attributesSchema ? templateAttributesSchema.merge(options.attributesSchema) : templateAttributesSchema;
-        let attributesParseResult = attributesSchema.safeParse(attributes);
+        let attributesParseResult = attributesSchema.safeParse(rawAttributes);
         if (!attributesParseResult.success) {
             throw new TemplateError('INVALID_ATTRIBUTES', {
                 cause: attributesParseResult.error,
@@ -66,6 +78,7 @@ import { TemplateError } from './TemplateError.js';
                 }
             });
         }
+        let attributes = attributesParseResult.data;
         return new this({
             path: templatePath,
             attributes,

package/dist/Template.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/Template.ts"],"sourcesContent":["import ejs from 'ejs';\nimport fs from 'fs-extra';\nimport matter from 'gray-matter';\nimport omit from 'lodash.omit';\nimport prettier from 'prettier';\nimport yaml from 'yaml';\nimport {type z, type AnyZodObject} from 'zod';\n\nimport {NO_INFERRED_PARSER_REGEXP} from './constants.js';\nimport {templateAttributesSchema, type TemplateAttributes} from './TemplateAttributes.js';\nimport {TemplateError} from './TemplateError.js';\nimport {type TemplateFunction} from './TemplateFunction.js';\nimport {type TemplateRender} from './TemplateRender.js';\nimport {type TemplateRenders} from './TemplateRenders.js';\n\nexport type TemplateOptions<\n  A extends AnyZodObject | undefined = undefined,\n  D extends AnyZodObject | undefined = undefined,\n> = {\n  /** Template path. */\n  path?: string;\n\n  /** Template content. */\n  content: string;\n\n  /** Template attributes.  */\n  attributes: A extends undefined\n    ? TemplateAttributes\n    : TemplateAttributes & z.infer<NonNullable<A>>;\n\n  /** Zod schema for custom template attributes. */\n  attributesSchema?: A | undefined;\n\n  /** Zod schema for template data. */\n  dataSchema?: D | undefined;\n};\n\nexport type TemplateReadOptions<\n  A extends AnyZodObject | undefined = undefined,\n  D extends AnyZodObject | undefined = undefined,\n> = {\n  /** Zod schema for custom template attributes. */\n  attributesSchema?: A | undefined;\n\n  /** Zod schema for template data. */\n  dataSchema?: D | undefined;\n};\n\nexport type TemplateReadAndRenderOptions<\n  A extends AnyZodObject | undefined = undefined,\n  D extends AnyZodObject | undefined = undefined,\n> = {\n  /** Prettier options.  */\n  prettierOptions?: prettier.Options | undefined;\n\n  /** Disable formatting the rendered template using Prettier.  */\n  disablePrettier?: boolean | undefined;\n\n  /** Zod schema for custom template attributes. */\n  attributesSchema?: A | undefined;\n\n  /** Zod schema for template data. */\n  dataSchema?: D | undefined;\n};\n\nexport type TemplateRenderOptions = {\n  /** Prettier options.  */\n  prettierOptions?: prettier.Options | undefined;\n\n  /** Disable formatting the rendered template using Prettier.  */\n  disablePrettier?: boolean | undefined;\n};\n\n/**\n * The `Template` object stores all information about a template and has methods for reading and rendering.\n *\n * ```TypeScript\n * let template = new Template({\n *   content: '<%- value %>',\n *   attributes: {\n *     to: 'value.txt',\n *   },\n *   dataSchema: z.object({value: z.number()}),\n * });\n *\n * console.log(await template.render({value: 42})); // ->  [{attributes: {to: 'value.txt'}, data: {value: 42}, content: '42'}]\n * ```\n *\n * @typeParam A A Zod schema type used to define the custom template attributes type.\n * @typeParam D A Zod schema type used to define the template datatype.\n */\nexport class Template<\n  A extends AnyZodObject | undefined = undefined,\n  D extends AnyZodObject | undefined = undefined,\n> {\n  /** Template path. */\n  path?: string;\n\n  /** Template content. Templates are written in [EJS](https://ejs.co/). */\n  readonly content: string;\n\n  /** 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. */\n  readonly attributes: A extends undefined\n    ? TemplateAttributes\n    : TemplateAttributes & z.infer<NonNullable<A>>;\n\n  /** Template function. */\n  private readonly fn: TemplateFunction;\n\n  /** Zod schema for custom template attributes. */\n  readonly attributesSchema: A extends AnyZodObject ? A : null;\n\n  /** Zod schema for template data. */\n  readonly dataSchema: D extends AnyZodObject ? D : null;\n\n  constructor({path, content, attributes, attributesSchema, dataSchema}: TemplateOptions<A, D>) {\n    if (path) {\n      this.path = path;\n    }\n\n    this.content = content;\n    this.attributes = attributes;\n    this.fn = ejs.compile(this.content);\n\n    if (attributesSchema) {\n      this.attributesSchema = attributesSchema as A extends AnyZodObject ? A : null;\n    } else {\n      this.attributesSchema = null as A extends AnyZodObject ? A : null;\n    }\n\n    if (dataSchema) {\n      this.dataSchema = dataSchema as D extends AnyZodObject ? D : null;\n    } else {\n      this.dataSchema = null as D extends AnyZodObject ? D : null;\n    }\n  }\n\n  /**\n   * Reads a template from a file.\n   *\n   * @param templatePath Path to the template file.\n   */\n  static async read<\n    A extends AnyZodObject | undefined = undefined,\n    D extends AnyZodObject | undefined = undefined,\n  >(templatePath: string, options?: TemplateReadOptions<A, D>): Promise<Template<A, D>> {\n    let {data: attributes, content} = matter(await fs.readFile(templatePath, 'utf8'));\n    let attributesSchema = options?.attributesSchema\n      ? templateAttributesSchema.merge(options.attributesSchema)\n      : templateAttributesSchema;\n    let attributesParseResult = attributesSchema.safeParse(attributes);\n\n    if (!attributesParseResult.success) {\n      throw new TemplateError('INVALID_ATTRIBUTES', {\n        cause: attributesParseResult.error,\n        data: {\n          path: templatePath,\n          zodIssues: attributesParseResult.error.issues,\n        },\n      });\n    }\n\n    return new this({\n      path: templatePath,\n      attributes,\n      content,\n      attributesSchema: options?.attributesSchema,\n      dataSchema: options?.dataSchema,\n    } as TemplateOptions<A, D>);\n  }\n\n  /**\n   * Reads a template from a file and then renders it.\n   *\n   * @param templatePath Path to the template file.\n   * @param data Data used for rendering the template.\n   * @param options Options object.\n   * @return Template renders.\n   */\n  static async readAndRender<\n    A extends AnyZodObject | undefined = undefined,\n    D extends AnyZodObject | undefined = undefined,\n  >(\n    templatePath: string,\n    data: D extends undefined ? null : z.infer<NonNullable<D>>,\n    options?: TemplateReadAndRenderOptions<A, D>,\n  ) {\n    let template = await Template.read<A, D>(templatePath, {\n      attributesSchema: options?.attributesSchema,\n      dataSchema: options?.dataSchema,\n    });\n\n    return template.render(data, {\n      prettierOptions: options?.prettierOptions,\n      disablePrettier: options?.disablePrettier,\n    });\n  }\n\n  /**\n   * Renders the template using data.\n   *\n   * @param data Data used for rendering the template.\n   * @param options Options object.\n   * @return Template renders.\n   */\n  async render(\n    data: D extends undefined ? null : z.infer<NonNullable<D>>,\n    options?: TemplateRenderOptions,\n  ): Promise<TemplateRenders<A, D>> {\n    let renders: TemplateRenders<A, D> = [];\n\n    for (let variables of Array.isArray(this.attributes.variables)\n      ? this.attributes.variables\n      : [this.attributes.variables]) {\n      let renderedAttributes = omit(this.attributes, ['if']);\n      let renderedVariables = variables;\n\n      if (renderedVariables) {\n        for (let [variableName, variableValue] of Object.entries(renderedVariables)) {\n          if (typeof variableValue === 'string') {\n            renderedVariables[variableName] = ejs.render(variableValue, {...data});\n          } else {\n            renderedVariables[variableName] = variableValue;\n          }\n        }\n\n        renderedAttributes.variables = renderedVariables;\n      }\n\n      let dataWithAttributes = {...data, attributes: renderedAttributes};\n\n      if (this.attributes.if) {\n        let renderedIf = ejs.render(this.attributes.if, dataWithAttributes);\n        let parsedIf = yaml.parse(renderedIf) as unknown;\n\n        if (parsedIf === false) {\n          continue;\n        }\n      }\n\n      renderedAttributes.to = ejs.render(renderedAttributes.to, dataWithAttributes);\n      dataWithAttributes.attributes = renderedAttributes;\n\n      let content;\n\n      try {\n        content = this.fn(dataWithAttributes);\n      } catch (error: unknown) {\n        throw new TemplateError('FAILED_RENDER', {cause: error});\n      }\n\n      if (!options?.disablePrettier) {\n        try {\n          content = await prettier.format(content, {\n            ...options?.prettierOptions,\n            filepath: renderedAttributes.to,\n          });\n        } catch (error: unknown) {\n          if (!NO_INFERRED_PARSER_REGEXP.test((error as Error).message)) {\n            throw new TemplateError('FAILED_FORMAT', {cause: error});\n          }\n        }\n      }\n\n      renders.push({\n        attributes: renderedAttributes,\n        data: data ?? null,\n        content,\n      } as TemplateRender<A, D>);\n    }\n\n    return renders;\n  }\n}\n"],"names":["ejs","fs","matter","omit","prettier","yaml","NO_INFERRED_PARSER_REGEXP","templateAttributesSchema","TemplateError","Template","path","content","attributes","fn","attributesSchema","dataSchema","constructor","compile","read","templatePath","options","data","readFile","merge","attributesParseResult","safeParse","success","cause","error","zodIssues","issues","readAndRender","template","render","prettierOptions","disablePrettier","renders","variables","Array","isArray","renderedAttributes","renderedVariables","variableName","variableValue","Object","entries","dataWithAttributes","if","renderedIf","parsedIf","parse","to","format","filepath","test","message","push"],"mappings":"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"}
+{"version":3,"sources":["../src/Template.ts"],"sourcesContent":["import ejs from 'ejs';\nimport fs from 'fs-extra';\nimport matter from 'gray-matter';\nimport merge from 'lodash.merge';\nimport omit from 'lodash.omit';\nimport path from 'node:path';\nimport prettier from 'prettier';\nimport yaml from 'yaml';\nimport {type z, type AnyZodObject} from 'zod';\n\nimport {NO_INFERRED_PARSER_REGEXP} from './constants.js';\nimport {templateAttributesSchema, type TemplateAttributes} from './TemplateAttributes.js';\nimport {TemplateError} from './TemplateError.js';\nimport {type TemplateFunction} from './TemplateFunction.js';\nimport {type TemplateRender} from './TemplateRender.js';\nimport {type TemplateRenders} from './TemplateRenders.js';\n\nexport type TemplateOptions<\n  A extends AnyZodObject | undefined = undefined,\n  D extends AnyZodObject | undefined = undefined,\n> = {\n  /** Template path. */\n  path?: string;\n\n  /** Template content. */\n  content: string;\n\n  /** Template attributes.  */\n  attributes: A extends undefined\n    ? TemplateAttributes\n    : TemplateAttributes & z.infer<NonNullable<A>>;\n\n  /** Zod schema for custom template attributes. */\n  attributesSchema?: A | undefined;\n\n  /** Zod schema for template data. */\n  dataSchema?: D | undefined;\n};\n\nexport type TemplateReadOptions<\n  A extends AnyZodObject | undefined = undefined,\n  D extends AnyZodObject | undefined = undefined,\n> = {\n  /** Zod schema for custom template attributes. */\n  attributesSchema?: A | undefined;\n\n  /** Zod schema for template data. */\n  dataSchema?: D | undefined;\n};\n\nexport type TemplateReadAndRenderOptions<\n  A extends AnyZodObject | undefined = undefined,\n  D extends AnyZodObject | undefined = undefined,\n> = {\n  /** Prettier options.  */\n  prettierOptions?: prettier.Options | undefined;\n\n  /** Disable formatting the rendered template using Prettier.  */\n  disablePrettier?: boolean | undefined;\n\n  /** Zod schema for custom template attributes. */\n  attributesSchema?: A | undefined;\n\n  /** Zod schema for template data. */\n  dataSchema?: D | undefined;\n};\n\nexport type TemplateRenderOptions = {\n  /** Prettier options.  */\n  prettierOptions?: prettier.Options | undefined;\n\n  /** Disable formatting the rendered template using Prettier.  */\n  disablePrettier?: boolean | undefined;\n};\n\n/**\n * The `Template` object stores all information about a template and has methods for reading and rendering.\n *\n * ```TypeScript\n * let template = new Template({\n *   content: '<%- value %>',\n *   attributes: {\n *     to: 'value.txt',\n *   },\n *   dataSchema: z.object({value: z.number()}),\n * });\n *\n * console.log(await template.render({value: 42})); // ->  [{attributes: {to: 'value.txt'}, data: {value: 42}, content: '42'}]\n * ```\n *\n * @typeParam A A Zod schema type used to define the custom template attributes type.\n * @typeParam D A Zod schema type used to define the template datatype.\n */\nexport class Template<\n  A extends AnyZodObject | undefined = undefined,\n  D extends AnyZodObject | undefined = undefined,\n> {\n  /** Template path. */\n  path?: string;\n\n  /** Template content. Templates are written in [EJS](https://ejs.co/). */\n  readonly content: string;\n\n  /** 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. */\n  readonly attributes: A extends undefined\n    ? TemplateAttributes\n    : TemplateAttributes & z.infer<NonNullable<A>>;\n\n  /** Template function. */\n  private readonly fn: TemplateFunction;\n\n  /** Zod schema for custom template attributes. */\n  readonly attributesSchema: A extends AnyZodObject ? A : null;\n\n  /** Zod schema for template data. */\n  readonly dataSchema: D extends AnyZodObject ? D : null;\n\n  constructor({\n    path: templatePath,\n    content,\n    attributes,\n    attributesSchema,\n    dataSchema,\n  }: TemplateOptions<A, D>) {\n    if (templatePath) {\n      this.path = templatePath;\n    }\n\n    this.content = content;\n    this.attributes = attributes;\n    this.fn = ejs.compile(this.content);\n\n    if (attributesSchema) {\n      this.attributesSchema = attributesSchema as A extends AnyZodObject ? A : null;\n    } else {\n      this.attributesSchema = null as A extends AnyZodObject ? A : null;\n    }\n\n    if (dataSchema) {\n      this.dataSchema = dataSchema as D extends AnyZodObject ? D : null;\n    } else {\n      this.dataSchema = null as D extends AnyZodObject ? D : null;\n    }\n  }\n\n  /**\n   * Reads a template from a file.\n   *\n   * @param templatePath Path to the template file.\n   */\n  static async read<\n    A extends AnyZodObject | undefined = undefined,\n    D extends AnyZodObject | undefined = undefined,\n  >(templatePath: string, options?: TemplateReadOptions<A, D>): Promise<Template<A, D>> {\n    let {data: rawAttributes, content} = matter(await fs.readFile(templatePath, 'utf8'));\n\n    // extending another template\n    if (typeof rawAttributes.extends === 'string' && rawAttributes.extends) {\n      let extendedTemplate = await Template.read(\n        path.join(path.dirname(templatePath), rawAttributes.extends),\n        options,\n      ); // you can point to any template, but it will be parsed with the same options, including attribute or data schema\n\n      // attributes are recursively merged\n      rawAttributes = merge(extendedTemplate.attributes, rawAttributes);\n\n      // if content is empty, use content from the extended template\n      if (!content.trim()) {\n        content = extendedTemplate.content;\n      }\n    }\n\n    let attributesSchema = options?.attributesSchema\n      ? templateAttributesSchema.merge(options.attributesSchema)\n      : templateAttributesSchema;\n    let attributesParseResult = attributesSchema.safeParse(rawAttributes);\n\n    if (!attributesParseResult.success) {\n      throw new TemplateError('INVALID_ATTRIBUTES', {\n        cause: attributesParseResult.error,\n        data: {\n          path: templatePath,\n          zodIssues: attributesParseResult.error.issues,\n        },\n      });\n    }\n\n    let attributes = attributesParseResult.data;\n\n    return new this({\n      path: templatePath,\n      attributes,\n      content,\n      attributesSchema: options?.attributesSchema,\n      dataSchema: options?.dataSchema,\n    } as TemplateOptions<A, D>);\n  }\n\n  /**\n   * Reads a template from a file and then renders it.\n   *\n   * @param templatePath Path to the template file.\n   * @param data Data used for rendering the template.\n   * @param options Options object.\n   * @return Template renders.\n   */\n  static async readAndRender<\n    A extends AnyZodObject | undefined = undefined,\n    D extends AnyZodObject | undefined = undefined,\n  >(\n    templatePath: string,\n    data: D extends undefined ? null : z.infer<NonNullable<D>>,\n    options?: TemplateReadAndRenderOptions<A, D>,\n  ) {\n    let template = await Template.read<A, D>(templatePath, {\n      attributesSchema: options?.attributesSchema,\n      dataSchema: options?.dataSchema,\n    });\n\n    return template.render(data, {\n      prettierOptions: options?.prettierOptions,\n      disablePrettier: options?.disablePrettier,\n    });\n  }\n\n  /**\n   * Renders the template using data.\n   *\n   * @param data Data used for rendering the template.\n   * @param options Options object.\n   * @return Template renders.\n   */\n  async render(\n    data: D extends undefined ? null : z.infer<NonNullable<D>>,\n    options?: TemplateRenderOptions,\n  ): Promise<TemplateRenders<A, D>> {\n    let renders: TemplateRenders<A, D> = [];\n\n    for (let variables of Array.isArray(this.attributes.variables)\n      ? this.attributes.variables\n      : [this.attributes.variables]) {\n      let renderedAttributes = omit(this.attributes, ['if']);\n      let renderedVariables = variables;\n\n      if (renderedVariables) {\n        for (let [variableName, variableValue] of Object.entries(renderedVariables)) {\n          if (typeof variableValue === 'string') {\n            renderedVariables[variableName] = ejs.render(variableValue, {...data});\n          } else {\n            renderedVariables[variableName] = variableValue;\n          }\n        }\n\n        renderedAttributes.variables = renderedVariables;\n      }\n\n      let dataWithAttributes = {...data, attributes: renderedAttributes};\n\n      if (this.attributes.if) {\n        let renderedIf = ejs.render(this.attributes.if, dataWithAttributes);\n        let parsedIf = yaml.parse(renderedIf) as unknown;\n\n        if (parsedIf === false) {\n          continue;\n        }\n      }\n\n      renderedAttributes.to = ejs.render(renderedAttributes.to, dataWithAttributes);\n      dataWithAttributes.attributes = renderedAttributes;\n\n      let content;\n\n      try {\n        content = this.fn(dataWithAttributes);\n      } catch (error: unknown) {\n        throw new TemplateError('FAILED_RENDER', {cause: error});\n      }\n\n      if (!options?.disablePrettier) {\n        try {\n          content = await prettier.format(content, {\n            ...options?.prettierOptions,\n            filepath: renderedAttributes.to,\n          });\n        } catch (error: unknown) {\n          if (!NO_INFERRED_PARSER_REGEXP.test((error as Error).message)) {\n            throw new TemplateError('FAILED_FORMAT', {cause: error});\n          }\n        }\n      }\n\n      renders.push({\n        attributes: renderedAttributes,\n        data: data ?? null,\n        content,\n      } as TemplateRender<A, D>);\n    }\n\n    return renders;\n  }\n}\n"],"names":["ejs","fs","matter","merge","omit","path","prettier","yaml","NO_INFERRED_PARSER_REGEXP","templateAttributesSchema","TemplateError","Template","content","attributes","fn","attributesSchema","dataSchema","constructor","templatePath","compile","read","options","data","rawAttributes","readFile","extends","extendedTemplate","join","dirname","trim","attributesParseResult","safeParse","success","cause","error","zodIssues","issues","readAndRender","template","render","prettierOptions","disablePrettier","renders","variables","Array","isArray","renderedAttributes","renderedVariables","variableName","variableValue","Object","entries","dataWithAttributes","if","renderedIf","parsedIf","parse","to","format","filepath","test","message","push"],"mappings":"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"}

package/dist/TemplateAttributes.d.ts

@@ -3,15 +3,18 @@ import { z } from 'zod';
  * Zod schema for {@link TemplateAttributes}.
  */
 export declare const templateAttributesSchema: z.ZodObject<{
+    extends: z.ZodOptional<z.ZodString>;
     to: z.ZodString;
     if: z.ZodOptional<z.ZodString>;
     variables: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>, "many">]>>;
 }, "strict", z.ZodTypeAny, {
     to: string;
+    extends?: string | undefined;
     if?: string | undefined;
     variables?: Record<string, unknown> | Record<string, unknown>[] | undefined;
 }, {
     to: string;
+    extends?: string | undefined;
     if?: string | undefined;
     variables?: Record<string, unknown> | Record<string, unknown>[] | undefined;
 }>;

package/dist/TemplateAttributes.js

@@ -3,6 +3,7 @@ import { templateVariablesSchema } from './TemplateVariables.js';
 /**
  * Zod schema for {@link TemplateAttributes}.
  */ export const templateAttributesSchema = z.object({
+    extends: z.string().optional(),
     to: z.string(),
     if: z.string().optional(),
     variables: templateVariablesSchema.optional()

package/dist/TemplateAttributes.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/TemplateAttributes.ts"],"sourcesContent":["import {z} from 'zod';\n\nimport {templateVariablesSchema} from './TemplateVariables.js';\n\n/**\n * Zod schema for {@link TemplateAttributes}.\n */\nexport const templateAttributesSchema = z\n  .object({\n    to: z.string(),\n    if: z.string().optional(),\n    variables: templateVariablesSchema.optional(),\n  })\n  .strict();\n\n/**\n * Type representing template attributes.\n */\nexport type TemplateAttributes = z.infer<typeof templateAttributesSchema>;\n"],"names":["z","templateVariablesSchema","templateAttributesSchema","object","to","string","if","optional","variables","strict"],"mappings":"AAAA,SAAQA,CAAC,QAAO,MAAM;AAEtB,SAAQC,uBAAuB,QAAO,yBAAyB;AAE/D;;CAEC,GACD,OAAO,MAAMC,2BAA2BF,EACrCG,MAAM,CAAC;IACNC,IAAIJ,EAAEK,MAAM;IACZC,IAAIN,EAAEK,MAAM,GAAGE,QAAQ;IACvBC,WAAWP,wBAAwBM,QAAQ;AAC7C,GACCE,MAAM,GAAG"}
+{"version":3,"sources":["../src/TemplateAttributes.ts"],"sourcesContent":["import {z} from 'zod';\n\nimport {templateVariablesSchema} from './TemplateVariables.js';\n\n/**\n * Zod schema for {@link TemplateAttributes}.\n */\nexport const templateAttributesSchema = z\n  .object({\n    extends: z.string().optional(),\n    to: z.string(),\n    if: z.string().optional(),\n    variables: templateVariablesSchema.optional(),\n  })\n  .strict();\n\n/**\n * Type representing template attributes.\n */\nexport type TemplateAttributes = z.infer<typeof templateAttributesSchema>;\n"],"names":["z","templateVariablesSchema","templateAttributesSchema","object","extends","string","optional","to","if","variables","strict"],"mappings":"AAAA,SAAQA,CAAC,QAAO,MAAM;AAEtB,SAAQC,uBAAuB,QAAO,yBAAyB;AAE/D;;CAEC,GACD,OAAO,MAAMC,2BAA2BF,EACrCG,MAAM,CAAC;IACNC,SAASJ,EAAEK,MAAM,GAAGC,QAAQ;IAC5BC,IAAIP,EAAEK,MAAM;IACZG,IAAIR,EAAEK,MAAM,GAAGC,QAAQ;IACvBG,WAAWR,wBAAwBK,QAAQ;AAC7C,GACCI,MAAM,GAAG"}

package/dist/TemplateError.js

@@ -4,7 +4,7 @@ import { createCustomErrorWithData } from '@jakubmazanec/error';
  */ export const TemplateError = createCustomErrorWithData('TemplateError', {
     INVALID_ATTRIBUTES: 'Invalid template attributes.',
     FAILED_FORMAT: 'Template render formatting has failed.',
-    FAILED_RENDER: 'Rendering has failed.'
+    FAILED_RENDER: 'Template rendering has failed.'
 }, class TemplateErrorData {
     template;
     path;

package/dist/TemplateError.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/TemplateError.ts"],"sourcesContent":["import {createCustomErrorWithData} from '@jakubmazanec/error';\nimport {type ZodIssue} from 'zod';\n\nimport {type Template} from './Template.js';\n\n/**\n * A subclass of `Error` that indicates a template  failure.\n */\nexport const TemplateError = createCustomErrorWithData(\n  'TemplateError',\n  {\n    INVALID_ATTRIBUTES: 'Invalid template attributes.',\n    FAILED_FORMAT: 'Template render formatting has failed.',\n    FAILED_RENDER: 'Rendering has failed.',\n  },\n  class TemplateErrorData {\n    template?: Template;\n    path?: string;\n    zodIssues?: ZodIssue[];\n  },\n);\n"],"names":["createCustomErrorWithData","TemplateError","INVALID_ATTRIBUTES","FAILED_FORMAT","FAILED_RENDER","TemplateErrorData","template","path","zodIssues"],"mappings":"AAAA,SAAQA,yBAAyB,QAAO,sBAAsB;AAK9D;;CAEC,GACD,OAAO,MAAMC,gBAAgBD,0BAC3B,iBACA;IACEE,oBAAoB;IACpBC,eAAe;IACfC,eAAe;AACjB,GACA,MAAMC;IACJC,SAAoB;IACpBC,KAAc;IACdC,UAAuB;AACzB,GACA"}
+{"version":3,"sources":["../src/TemplateError.ts"],"sourcesContent":["import {createCustomErrorWithData} from '@jakubmazanec/error';\nimport {type ZodIssue} from 'zod';\n\nimport {type Template} from './Template.js';\n\n/**\n * A subclass of `Error` that indicates a template  failure.\n */\nexport const TemplateError = createCustomErrorWithData(\n  'TemplateError',\n  {\n    INVALID_ATTRIBUTES: 'Invalid template attributes.',\n    FAILED_FORMAT: 'Template render formatting has failed.',\n    FAILED_RENDER: 'Template rendering has failed.',\n  },\n  class TemplateErrorData {\n    template?: Template;\n    path?: string;\n    zodIssues?: ZodIssue[];\n  },\n);\n"],"names":["createCustomErrorWithData","TemplateError","INVALID_ATTRIBUTES","FAILED_FORMAT","FAILED_RENDER","TemplateErrorData","template","path","zodIssues"],"mappings":"AAAA,SAAQA,yBAAyB,QAAO,sBAAsB;AAK9D;;CAEC,GACD,OAAO,MAAMC,gBAAgBD,0BAC3B,iBACA;IACEE,oBAAoB;IACpBC,eAAe;IACfC,eAAe;AACjB,GACA,MAAMC;IACJC,SAAoB;IACpBC,KAAc;IACdC,UAAuB;AACzB,GACA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jakubmazanec/template",
-  "version": "1.0.3",
+  "version": "1.1.0-next.5d8abeb",
   "description": "TypeScript-first library for working with templates using EJS and Zod.",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
     "ejs": "^3.1.9",
     "fs-extra": "^11.1.1",
     "gray-matter": "^4.0.3",
+    "lodash.merge": "^4.6.2",
     "lodash.omit": "^4.5.0",
     "prettier": "^3.0.0",
     "yaml": "^2.2.1",
@@ -39,6 +40,7 @@
     "@jest/globals": "^29.5.0",
     "@types/ejs": "^3.1.2",
     "@types/fs-extra": "^11.0.1",
+    "@types/lodash.merge": "^4.6.7",
     "@types/lodash.omit": "^4.5.7",
     "@types/node": "^16.18.3"
   },

package/src/Template.ts

@@ -1,7 +1,9 @@
 import ejs from 'ejs';
 import fs from 'fs-extra';
 import matter from 'gray-matter';
+import merge from 'lodash.merge';
 import omit from 'lodash.omit';
+import path from 'node:path';
 import prettier from 'prettier';
 import yaml from 'yaml';
 import {type z, type AnyZodObject} from 'zod';
@@ -113,9 +115,15 @@ export class Template<
   /** Zod schema for template data. */
   readonly dataSchema: D extends AnyZodObject ? D : null;
 
-  constructor({path, content, attributes, attributesSchema, dataSchema}: TemplateOptions<A, D>) {
-    if (path) {
-      this.path = path;
+  constructor({
+    path: templatePath,
+    content,
+    attributes,
+    attributesSchema,
+    dataSchema,
+  }: TemplateOptions<A, D>) {
+    if (templatePath) {
+      this.path = templatePath;
     }
 
     this.content = content;
@@ -144,11 +152,28 @@ export class Template<
     A extends AnyZodObject | undefined = undefined,
     D extends AnyZodObject | undefined = undefined,
   >(templatePath: string, options?: TemplateReadOptions<A, D>): Promise<Template<A, D>> {
-    let {data: attributes, content} = matter(await fs.readFile(templatePath, 'utf8'));
+    let {data: rawAttributes, content} = matter(await fs.readFile(templatePath, 'utf8'));
+
+    // extending another template
+    if (typeof rawAttributes.extends === 'string' && rawAttributes.extends) {
+      let extendedTemplate = await Template.read(
+        path.join(path.dirname(templatePath), rawAttributes.extends),
+        options,
+      ); // you can point to any template, but it will be parsed with the same options, including attribute or data schema
+
+      // attributes are recursively merged
+      rawAttributes = merge(extendedTemplate.attributes, rawAttributes);
+
+      // if content is empty, use content from the extended template
+      if (!content.trim()) {
+        content = extendedTemplate.content;
+      }
+    }
+
     let attributesSchema = options?.attributesSchema
       ? templateAttributesSchema.merge(options.attributesSchema)
       : templateAttributesSchema;
-    let attributesParseResult = attributesSchema.safeParse(attributes);
+    let attributesParseResult = attributesSchema.safeParse(rawAttributes);
 
     if (!attributesParseResult.success) {
       throw new TemplateError('INVALID_ATTRIBUTES', {
@@ -160,6 +185,8 @@ export class Template<
       });
     }
 
+    let attributes = attributesParseResult.data;
+
     return new this({
       path: templatePath,
       attributes,

package/src/TemplateAttributes.ts

@@ -7,6 +7,7 @@ import {templateVariablesSchema} from './TemplateVariables.js';
  */
 export const templateAttributesSchema = z
   .object({
+    extends: z.string().optional(),
     to: z.string(),
     if: z.string().optional(),
     variables: templateVariablesSchema.optional(),

package/src/TemplateError.ts

@@ -11,7 +11,7 @@ export const TemplateError = createCustomErrorWithData(
   {
     INVALID_ATTRIBUTES: 'Invalid template attributes.',
     FAILED_FORMAT: 'Template render formatting has failed.',
-    FAILED_RENDER: 'Rendering has failed.',
+    FAILED_RENDER: 'Template rendering has failed.',
   },
   class TemplateErrorData {
     template?: Template;