feat: support Jekyll style where, #768

Author: harttle

docs/package.json

@@ -3,7 +3,7 @@
   "version": "0.0.0",
   "private": true,
   "hexo": {
-    "version": "7.3.0"
+    "version": "5.4.0"
   },
   "scripts": {
     "build": "hexo generate",
@@ -34,4 +34,4 @@
   "engines": {
     "node": ">=8.10.0"
   }
-}
+}

docs/source/filters/where.md

@@ -103,4 +103,30 @@ Output
 - 3
 ```
 
+## Jekyll style
+
+{% since %}v10.19.0{% endsince %}
+
+For Liquid users migrating from Jekyll, there's a `jekyllWhere` option to mimic the behavior of Jekyll's `where` filter. This option is set to `false` by default. When enabled, if `property` is an array, the target value is matched using `Array.includes` instead of `==`, which is particularly useful for filtering tags.
+
+```javascript
+const pages = [
+    { tags: ["cat", "food"], title: 'Cat Food' },
+    { tags: ["dog", "food"], title: 'Dog Food' },
+]
+```
+
+Input
+```liquid
+{% assign selected = pages | where: 'tags', "cat" %}
+{% for item in selected -%}
+- {{ item.title }}
+{% endfor %}
+```
+
+Output
+```text
+Cat Food
+```
+
 [truthy]: ../tutorials/truthy-and-falsy.html

docs/source/zh-cn/filters/where.md

@@ -103,5 +103,32 @@ const products = [
 - 3
 ```
 
+## Jekyll 风格
+
+{% since %}v10.19.0{% endsince %}
+
+对于从 Jekyll 迁移到 Liquid 的用户，有一个 `jekyllWhere` 选项可以模拟 Jekyll 的 `where` 过滤器的行为。该选项默认设置为 `false`。启用后，如果 `property` 是一个数组，目标值将使用 `Array.includes` 而不是 `==` 进行匹配，这在过滤标签时特别有用。
+
+例如，以下代码：
+
+```javascript
+const pages = [
+    { tags: ["cat", "food"], title: 'Cat Food' },
+    { tags: ["dog", "food"], title: 'Dog Food' },
+]
+```
+
+输入
+```liquid
+{% assign selected = pages | where: 'tags', "cat" %}
+{% for item in selected -%}
+- {{ item.title }}
+{% endfor %}
+```
+
+输出
+```text
+Cat Food
+```
 
 [truthy]: ../tutorials/truthy-and-falsy.html

src/drop/blank-drop.ts

@@ -8,4 +8,7 @@ export class BlankDrop extends EmptyDrop {
     if (isString(value)) return /^\s*$/.test(value)
     return super.equals(value)
   }
+  static is (value: unknown) {
+    return value instanceof BlankDrop
+  }
 }

src/drop/empty-drop.ts

@@ -25,4 +25,7 @@ export class EmptyDrop extends Drop implements Comparable {
   public valueOf () {
     return ''
   }
+  static is (value: unknown) {
+    return value instanceof EmptyDrop
+  }
 }

src/filters/array.ts

@@ -1,8 +1,9 @@
 import { toArray, argumentsToValue, toValue, stringify, caseInsensitiveCompare, isArray, isNil, last as arrayLast } from '../util'
-import { equals, evalToken, isTruthy } from '../render'
+import { arrayIncludes, equals, evalToken, isTruthy } from '../render'
 import { Value, FilterImpl } from '../template'
 import { Tokenizer } from '../parser'
 import type { Scope } from '../context'
+import { EmptyDrop } from '../drop'
 
 export const join = argumentsToValue(function (this: FilterImpl, v: any[], arg: string) {
   const array = toArray(v)
@@ -124,9 +125,12 @@ export function * where<T extends object> (this: FilterImpl, arr: T[], property:
   for (const item of arr) {
     values.push(yield evalToken(token, this.context.spawn(item)))
   }
+  const matcher = this.context.opts.jekyllWhere
+    ? (v: any) => EmptyDrop.is(expected) ? equals(v, expected) : (isArray(v) ? arrayIncludes(v, expected) : equals(v, expected))
+    : (v: any) => equals(v, expected)
   return arr.filter((_, i) => {
     if (expected === undefined) return isTruthy(values[i], this.context)
-    return equals(values[i], expected)
+    return matcher(values[i])
   })
 }
 

src/liquid-options.ts

@@ -22,6 +22,8 @@ export interface LiquidOptions {
   relativeReference?: boolean;
   /** Use jekyll style include, pass parameters to `include` variable of current scope. Defaults to `false`. */
   jekyllInclude?: boolean;
+  /** Use jekyll style where filter, enables array item match. Defaults to `false`. */
+  jekyllWhere?: boolean;
   /** Add a extname (if filepath doesn't include one) before template file lookup. Eg: setting to `".html"` will allow including file by basename. Defaults to `""`. */
   extname?: string;
   /** Whether or not to cache resolved templates. Defaults to `false`. */

src/render/operator.ts

@@ -58,3 +58,7 @@ function arrayEquals (lhs: any[], rhs: any[]): boolean {
   if (lhs.length !== rhs.length) return false
   return !lhs.some((value, i) => !equals(value, rhs[i]))
 }
+
+export function arrayIncludes (arr: any[], item: any): boolean {
+  return arr.some(value => equals(value, item))
+}

test/integration/filters/array.spec.ts

@@ -484,6 +484,28 @@ describe('filters/array', function () {
         Kitchen products:
         `)
     })
+    it('should support nil as target', () => {
+      const scope = { list: [{ foo: 'FOO' }, { bar: 'BAR', type: 2 }] }
+      return test('{{list | where: "type", nil | json}}', scope, '[{"foo":"FOO"}]')
+    })
+    it('should support empty as target', async () => {
+      const scope = { pages: [{ tags: ['FOO'] }, { tags: [] }, { title: 'foo' }] }
+      await test('{{pages | where: "tags", empty | json}}', scope, '[{"tags":[]}]')
+    })
+    it('should not match string with array', async () => {
+      const scope = { objs: [{ foo: ['FOO', 'bar'] }] }
+      await test('{{objs | where: "foo", "FOO" | json}}', scope, '[]')
+    })
+    describe('jekyll style', () => {
+      it('should not match string with array', async () => {
+        const scope = { objs: [{ foo: ['FOO', 'bar'] }] }
+        await test('{{objs | where: "foo", "FOO" | json}}', scope, '[{"foo":["FOO","bar"]}]', { jekyllWhere: true })
+      })
+      it('should support empty as target', async () => {
+        const scope = { pages: [{ tags: ['FOO'] }, { tags: [] }, { title: 'foo' }] }
+        await test('{{pages | where: "tags", empty | json}}', scope, '[{"tags":[]}]', { jekyllWhere: true })
+      })
+    })
   })
   describe('where_exp', function () {
     const products = [