minijinja-js 3.0.0-alpha.2 → 3.0.0

package/README.md

@@ -88,29 +88,206 @@ const result = env.evalExpr('1 + 1', {});
 console.log(result);
 ```
 
+Register filters, tests and functions:
+
+```typescript
+import { Environment } from "minijinja-js";
+
+const env = new Environment();
+env.addFilter("repeat", (value, times, { sep = "" } = {}) =>
+  Array(times).fill(value).join(sep)
+);
+env.addGlobal("double", (x) => x * 2);
+console.log(env.renderStr("{{ 'ab'|repeat(3, sep='-') }} {{ double(21) }}"));
+// -> ab-ab-ab 42
+```
+
+Keyword arguments are passed to JavaScript callbacks as a trailing object.
+Exceptions thrown by callbacks fail the render with an error whose `cause`
+is the original exception.  Throw a `TemplateError` to fail with a specific
+error kind and message:
+
+```typescript
+import { TemplateError } from "minijinja-js";
+
+env.addFilter("sqrt", (value) => {
+  if (value < 0) {
+    throw new TemplateError("value must not be negative", { kind: "InvalidOperation" });
+  }
+  return Math.sqrt(value);
+});
+```
+
+Callbacks wrapped with `passState` receive the engine state as first
+argument.  It gives access to variables (`lookup`), the template name, the
+auto escape mode, and allows applying filters and tests.  The state is only
+valid while the callback runs:
+
+```typescript
+import { Environment, passState } from "minijinja-js";
+
+const env = new Environment();
+env.addFilter(
+  "greet",
+  passState((state, name) => `${state.lookup("greeting") ?? "Hello"} ${name}!`)
+);
+console.log(env.renderStr("{{ 'World'|greet }}", { greeting: "Hi" }));
+// -> Hi World!
+```
+
+The `random` filter as well as the `randrange` and `lipsum` functions are
+available.  Their output can be made deterministic with the `RAND_SEED` global.
+
+## Dates and Times
+
+Date and time filters can be enabled from `minijinja-js/datetime`.  They
+mirror the `datetimeformat`, `dateformat` and `timeformat` filters and the
+`now()` function from MiniJinja's contrib package but use the time zone
+support of the JavaScript runtime:
+
+```typescript
+import { Environment } from "minijinja-js";
+import { addDateTimeSupport } from "minijinja-js/datetime";
+
+const env = new Environment();
+addDateTimeSupport(env);
+env.addGlobal("TIMEZONE", "Europe/Vienna");
+console.log(env.renderStr("{{ ts|datetimeformat(format='full') }}", { ts: 1687624642 }));
+// -> Saturday, June 24 2023 18:37:22.0
+```
+
+The filters accept Unix timestamps, ISO 8601 strings (optionally with a time
+zone annotation such as `2023-06-24T16:37:22Z[Europe/Vienna]`) and `Date`
+objects.  The format is one of `short`, `medium` (the default), `long`,
+`full`, `iso` and `unix` or a `strftime` style format string.  The `format`
+and `tz` keyword arguments default to the `DATETIME_FORMAT`, `DATE_FORMAT`,
+`TIME_FORMAT` and `TIMEZONE` globals.
+
+## Values
+
+Values passed to templates are converted as follows:
+
+* `undefined` is undefined and `null` is none.
+* Numbers that are safe integers become integers, all others floats.
+  `BigInt`s become integers.
+* Arrays, `Set`s and typed arrays become sequences, `Uint8Array` and
+  `ArrayBuffer` become bytes.
+* Plain objects and `Map`s become maps.  Key order is preserved.
+* `Date`s become ISO 8601 strings.
+* Functions become callable.
+* Other objects (for instance class instances) are not copied but accessed
+  lazily.  This means getters work and methods are invoked with the object
+  as `this`.
+
+Values returned to JavaScript (from `evalExpr` or as arguments to
+callbacks) are converted back:
+
+* undefined becomes `undefined`, none becomes `null`.
+* Integers outside of the safe integer range become `BigInt`s.
+* Sequences become arrays, bytes become `Uint8Array`s.
+* Maps with only string keys become plain objects, other maps become `Map`s.
+* Functions and objects that came from JavaScript are passed back unchanged.
+
 MiniJinja tuples retain tuple rendering inside templates. Expression results are
 returned as JavaScript arrays because JavaScript has no distinct tuple type.
 
-## Web Usage
+## Configuration
 
-If you want to use minijinja-js from the browser instead of node, you will
-need to use slightly different imports and call init explicitly:
+```typescript
+import { Environment } from "minijinja-js";
+
+const env = new Environment();
+
+// whitespace handling and undefined behavior
+env.trimBlocks = true;
+env.lstripBlocks = true;
+env.undefinedBehavior = "strict";
+
+// custom delimiters and line statements (unspecified ones use the defaults)
+env.syntax = { variableStart: "${", variableEnd: "}", lineStatementPrefix: "#" };
+
+// auto escaping per template name: "html", "json", "none", true or false
+env.setAutoEscapeCallback((name) => name.endsWith(".html"));
+
+// customize values before they are rendered (return undefined to keep them)
+env.setFinalizer((value) => (value === null ? "" : undefined));
+
+// limit the amount of work a template can do
+env.fuel = 50000;
+
+// Python compatible methods such as dict.items()
+env.pycompat = true;
+```
+
+Find the variables a template needs:
+
+```typescript
+env.addTemplate("index.html", "{% set greeting = 'Hello' %}{{ greeting }} {{ user.name }}");
+env.undeclaredVariablesInTemplate("index.html"); // ["user"]
+env.undeclaredVariablesInTemplate("index.html", true); // ["user.name"]
+```
 
+## Safe Strings
+
+Strings marked as safe are not auto escaped.  Safe strings are represented
+by `SafeString` (which extends `String`) and can be created with `markSafe`.
+Callbacks receive safe strings (for instance after the `|safe` filter) as
+`SafeString` objects and can return them to emit markup:
+
+```typescript
+import { Environment, markSafe } from "minijinja-js";
+
+const env = new Environment();
+env.addFilter("bold", (value) => markSafe(`<b>${value}</b>`));
+env.addTemplate("index.html", "{{ name|bold }} {{ icon }}");
+console.log(env.renderTemplate("index.html", { name: "World", icon: markSafe("<i>*</i>") }));
+// -> <b>World</b> <i>*</i>
+```
+
+## Errors
+
+Errors are raised as `TemplateError` which extends `Error` and provides
+`kind`, `detail`, `templateName`, `line`, `range` and `templateSource`
+properties.  If the error was caused by an exception thrown in a callback,
+the exception is available as `cause`.
+
+## Runtimes
+
+The package is an ES module and works in Node.js, Deno, Bun, browsers and
+bundlers:
+
+* In Node.js the wasm module is loaded synchronously.  Recent Node.js versions
+  can also load the package with `require()`.
+* In all other environments the wasm module is loaded relative to the package
+  (via `import.meta.url`) with top-level await.
+
+If you need to control how the wasm module is loaded (for instance on
+Cloudflare Workers or with a custom asset pipeline), use the `minijinja-js/init`
+entry point and initialize the module yourself before use:
 
 ```javascript
-import init, { Environment } from "minijinja-js/dist/web";
-await init();
+import { init, initSync, Environment } from "minijinja-js/init";
+
+// load from a URL, Response or compiled module
+await init(new URL("minijinja_js_bg.wasm", someBaseUrl));
+
+// or synchronously from bytes or a compiled module
+initSync(wasmModule);
 ```
 
+The wasm file is exported as `minijinja-js/minijinja_js_bg.wasm`.
+
 ## Known Limitations
 
 There are various limitations with the binding today, some of which can be fixed,
 others probably not so much.  You might run into the following:
 
-* Access of the template engine state from JavaScript is not possible.
-* You cannot register a custom auto escape callback or a finalizer
+* Filters, tests and functions cannot be async.
 * The loader is synchronous; use sync I/O in Node etc... (e.g. `fs.readFileSync`)
-* If the engine panics, the WASM runtime corrupts.
+* The environment cannot be modified while it renders (for instance from
+  within a filter).
+* If the engine panics, the WASM runtime corrupts.  This should not happen
+  but if it does, please report it as a bug.
 
 ## Sponsor
 
@@ -120,5 +297,5 @@ sponsor](https://github.com/sponsors/mitsuhiko).
 ## License and Links
 
 - [Issue Tracker](https://github.com/mitsuhiko/minijinja/issues)
-- [MiniJinja Playground](https://mitsuhiko.github.io/minijinja-playground/)
+- [MiniJinja Playground](https://mitsuhiko.github.io/minijinja/)
 - License: [Apache-2.0](https://github.com/mitsuhiko/minijinja/blob/main/LICENSE)

package/dist/datetime.d.ts

@@ -0,0 +1,16 @@
+import type { Environment } from "./types.js";
+
+/**
+ * Registers the date and time filters and functions with an environment.
+ *
+ * This adds the `datetimeformat`, `dateformat` and `timeformat` filters and
+ * the `now` function.  They behave like the ones of the `datetime` feature
+ * of minijinja-contrib but use the time zone support of the JavaScript
+ * runtime (`Intl`).
+ *
+ * The filters accept Unix timestamps (seconds), ISO 8601 strings
+ * (optionally with a time zone annotation such as `[Europe/Vienna]`) and
+ * `Date` objects.  The `format` and `tz` keyword arguments default to the
+ * `DATETIME_FORMAT`, `DATE_FORMAT`, `TIME_FORMAT` and `TIMEZONE` globals.
+ */
+export declare function addDateTimeSupport(env: Environment): void;