fix(tags): empty template tag & add docs

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

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

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 {

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)