Added find-first and find-last formatters with corresponding tests

Author: lr-brown

__tests__/plugins/formatters.core.test.ts

@@ -370,6 +370,78 @@ loader.paths('f-json-pretty-%N.html').forEach((path) => {
   test(`json pretty - ${path}`, () => loader.execute(path));
 });
 
+test('find-first', () => {
+  // no args: return first element unconditionally
+  let vars = variables(['a', 'b', 'c']);
+  Core['find-first'].apply([], vars, CTX);
+  expect(vars[0].get()).toEqual('a');
+
+  // empty array → missing
+  vars = variables([]);
+  Core['find-first'].apply([], vars, CTX);
+  expect(vars[0].node.isMissing()).toBe(true);
+
+  // non-array → missing
+  vars = variables('not-an-array');
+  Core['find-first'].apply([], vars, CTX);
+  expect(vars[0].node.isMissing()).toBe(true);
+
+  // no args: first object element
+  vars = variables([{ x: 1 }, { x: 2 }]);
+  Core['find-first'].apply([], vars, CTX);
+  expect(vars[0].get()).toEqual({ x: 1 });
+
+  // 1 arg: find first element where path is truthy
+  vars = variables([{ id: 'a', enabled: false }, { id: 'b', enabled: true }, { id: 'c', enabled: true }]);
+  Core['find-first'].apply(['enabled'], vars, CTX);
+  expect(vars[0].get()).toEqual({ id: 'b', enabled: true });
+
+  // 1 arg: none match → missing
+  vars = variables([{ id: 'a', enabled: false }, { id: 'b' }]);
+  Core['find-first'].apply(['enabled'], vars, CTX);
+  expect(vars[0].node.isMissing()).toBe(true);
+});
+
+loader.paths('f-find-first-%N.html').forEach((path) => {
+  test(`find-first - ${path}`, () => loader.execute(path));
+});
+
+test('find-last', () => {
+  // no args: return last element unconditionally
+  let vars = variables(['a', 'b', 'c']);
+  Core['find-last'].apply([], vars, CTX);
+  expect(vars[0].get()).toEqual('c');
+
+  // empty array → missing
+  vars = variables([]);
+  Core['find-last'].apply([], vars, CTX);
+  expect(vars[0].node.isMissing()).toBe(true);
+
+  // non-array → missing
+  vars = variables('not-an-array');
+  Core['find-last'].apply([], vars, CTX);
+  expect(vars[0].node.isMissing()).toBe(true);
+
+  // no args: last object element
+  vars = variables([{ x: 1 }, { x: 2 }]);
+  Core['find-last'].apply([], vars, CTX);
+  expect(vars[0].get()).toEqual({ x: 2 });
+
+  // 1 arg: find last element where path is truthy
+  vars = variables([{ id: 'a', enabled: true }, { id: 'b', enabled: true }, { id: 'c', enabled: false }]);
+  Core['find-last'].apply(['enabled'], vars, CTX);
+  expect(vars[0].get()).toEqual({ id: 'b', enabled: true });
+
+  // 1 arg: none match → missing
+  vars = variables([{ id: 'a', enabled: false }, { id: 'b' }]);
+  Core['find-last'].apply(['enabled'], vars, CTX);
+  expect(vars[0].node.isMissing()).toBe(true);
+});
+
+loader.paths('f-find-last-%N.html').forEach((path) => {
+  test(`find-last - ${path}`, () => loader.execute(path));
+});
+
 test('key-by', () => {
   let vars = variables([{ id: 1 }]);
   Core['key-by'].apply([], vars, CTX);

__tests__/plugins/resources/f-find-first-1.html

@@ -0,0 +1,14 @@
+:JSON
+{
+  "items": [
+    { "id": "a", "enabled": false },
+    { "id": "b", "enabled": true },
+    { "id": "c", "enabled": true }
+  ]
+}
+
+:TEMPLATE
+{.var @first items|find-first enabled}{@first.id}
+
+:OUTPUT
+b

__tests__/plugins/resources/f-find-first-2.html

@@ -0,0 +1,15 @@
+:JSON
+{
+  "keys": ["a", "b", "c"],
+  "map": {
+    "a": { "enabled": false },
+    "b": { "enabled": true },
+    "c": { "enabled": true }
+  }
+}
+
+:TEMPLATE
+{keys|find-first map enabled}
+
+:OUTPUT
+b

__tests__/plugins/resources/f-find-last-1.html

@@ -0,0 +1,14 @@
+:JSON
+{
+  "items": [
+    { "id": "a", "enabled": true },
+    { "id": "b", "enabled": true },
+    { "id": "c", "enabled": false }
+  ]
+}
+
+:TEMPLATE
+{.var @last items|find-last enabled}{@last.id}
+
+:OUTPUT
+b

__tests__/plugins/resources/f-find-last-2.html

@@ -0,0 +1,15 @@
+:JSON
+{
+  "keys": ["a", "b", "c"],
+  "map": {
+    "a": { "enabled": true },
+    "b": { "enabled": true },
+    "c": { "enabled": false }
+  }
+}
+
+:TEMPLATE
+{keys|find-last map enabled}
+
+:OUTPUT
+b

src/plugins/formatters.core.ts

@@ -243,6 +243,59 @@ export class KeyByFormatter extends Formatter {
   }
 }
 
+export class FindFirstFormatter extends Formatter {
+  apply(args: string[], vars: Variable[], ctx: Context): void {
+    const first = vars[0];
+    if (first.node.type !== Type.ARRAY || first.node.value.length === 0) {
+      first.set(MISSING_NODE);
+      return;
+    }
+    if (args.length === 0) {
+      first.set(new Node(first.get()[0]));
+      return;
+    }
+    const hasLookup = args.length >= 2;
+    const lookup = hasLookup ? ctx.resolve(splitVariable(args[0])) : null;
+    const path = splitVariable(args[hasLookup ? 1 : 0]);
+    for (const val of first.get()) {
+      const element = new Node(val);
+      const candidate = hasLookup ? lookup!.path([element.asString()]) : element;
+      if (isTruthy(candidate.path(path))) {
+        first.set(element);
+        return;
+      }
+    }
+    first.set(MISSING_NODE);
+  }
+}
+
+export class FindLastFormatter extends Formatter {
+  apply(args: string[], vars: Variable[], ctx: Context): void {
+    const first = vars[0];
+    const arr: any[] = first.node.type === Type.ARRAY ? first.get() : null;
+    if (!arr || arr.length === 0) {
+      first.set(MISSING_NODE);
+      return;
+    }
+    if (args.length === 0) {
+      first.set(new Node(arr[arr.length - 1]));
+      return;
+    }
+    const hasLookup = args.length >= 2;
+    const lookup = hasLookup ? ctx.resolve(splitVariable(args[0])) : null;
+    const path = splitVariable(args[hasLookup ? 1 : 0]);
+    for (let i = arr.length - 1; i >= 0; i--) {
+      const element = new Node(arr[i]);
+      const candidate = hasLookup ? lookup!.path([element.asString()]) : element;
+      if (isTruthy(candidate.path(path))) {
+        first.set(element);
+        return;
+      }
+    }
+    first.set(MISSING_NODE);
+  }
+}
+
 const NEWLINE = /\n/g;
 
 export class LineBreaksFormatter extends Formatter {
@@ -421,6 +474,8 @@ export const CORE_FORMATTERS: FormatterTable = {
   'encode-space': new EncodeSpaceFormatter(),
   'encode-uri': new EncodeUriFormatter(),
   'encode-uri-component': new EncodeUriComponentFormatter(),
+  'find-first': new FindFirstFormatter(),
+  'find-last': new FindLastFormatter(),
   format: new FormatFormatter(),
   get: new GetFormatter(),
   html: new HtmlFormatter(),