From 9a3921e4115844e61ec8b0a3ab0dd8bd259e519b Mon Sep 17 00:00:00 2001
From: Sergey Kolesnik <sergey.s.kolesnik@gmail.com>
Date: Wed, 14 Feb 2024 03:02:11 +0300
Subject: [PATCH] fix(tags): `empty` template tag & add docs

---
 docs/reference__tags.md  | 29 +++++++++++++++++++++++++++--
 src/tags.ts              |  6 +++---
 tests/index.ts           |  1 +
 tests/tags/plain.test.ts |  3 +--
 4 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/docs/reference__tags.md b/docs/reference__tags.md
index c560169..d900a27 100644
--- a/docs/reference__tags.md
+++ b/docs/reference__tags.md
@@ -111,8 +111,33 @@ Call an `embed` macro for pages `{{embed [[page]] }}` or blocks `{{embed ((uuid.
 
 ## `String operations` :id=section-string
 
-### `empty TODO` :id=empty
-TODO
+### `empty` :id=empty
+Checks whether the object is empty or not. If it is empty it will be replaced with fallback object.
+
+`empty(obj, fallback = '') → obj, fallback`
+- `obj`: value to check for emptyness
+- `fallback`: replacement object (default: `''`)
+
+!> It is very different than JavaScript «empty» values. \
+\
+*Empty* values example: \
+`null`, `undefined`, `[]`, `{}`, `'     '`, `''`, `""`, ` `` `, `«»`, `-`, `—`, etc. \
+\
+*Non-empty* values example: \
+`0`, `false`, etc.
+
+<!-- tabs:start -->
+#### ***Template***
+` ``empty([1, 2, 3])`` ` \
+` ``empty([])`` ` \
+` ``empty([], 'empty array')`` `
+
+#### ***Rendered***
+[1, 2, 3] \
+\
+empty array
+<!-- tabs:end -->
+
 
 ### `when TODO` :id=when
 TODO
diff --git a/src/tags.ts b/src/tags.ts
index 76740b1..7527030 100644
--- a/src/tags.ts
+++ b/src/tags.ts
@@ -229,9 +229,9 @@ async function layout(context: ILogseqContext, name: string, args?: string[] | s
     return await _include(context, true, name, args)
 }
 
-function empty(obj: any, fallback: any = ''): any {
-    if (obj === null)
-        return obj
+function empty(obj: any, fallback: any = '') {
+    if (obj === null || obj === undefined)
+        return fallback
 
     if (Array.isArray(obj) && obj.length === 0)
         return fallback
diff --git a/tests/index.ts b/tests/index.ts
index 7ba6aac..1e72b6c 100644
--- a/tests/index.ts
+++ b/tests/index.ts
@@ -88,6 +88,7 @@ export async function LogseqMock(
             get_block: jest.fn(),
             get_page: jest.fn(),
             get_app_info: () => { return {} },
+            datascript_query: jest.fn(),
         },
 
         _createPage: function (name: string): PageEntity {
diff --git a/tests/tags/plain.test.ts b/tests/tags/plain.test.ts
index 182f81f..b5c31d8 100644
--- a/tests/tags/plain.test.ts
+++ b/tests/tags/plain.test.ts
@@ -191,13 +191,12 @@ describe('empty template tag', () => {
         expect( tags.empty({}) ).toBe('')
         expect( tags.empty([]) ).toBe('')
 
+        expect( tags.empty(null) ).toBe('')
         expect( tags.empty(undefined) ).toBe('')
     })
     test('non-empty values', () => {
         expect( tags.empty('page') ).toBe('page')
 
-        expect( tags.empty(null) ).toBe(null)
-
         expect( tags.empty(false) ).toBe(false)
         expect( tags.empty(true) ).toBe(true)