A lexicon-driven AppView for ATProto.
happyview.dev
backfill
firehose
jetstream
atproto
appview
oauth
lexicon
docs: add docs for utility globals
+61
+56
packages/docs/docs/reference/lua/utility-globals.md
+56
packages/docs/docs/reference/lua/utility-globals.md
···
1
+
# Utility Globals
2
+
3
+
Global functions available in queries, procedures, and [index hooks](../../guides/index-hooks.md). These don't belong to a specific API table — they're available at the top level of any Lua script.
4
+
5
+
## now
6
+
7
+
```lua
8
+
local timestamp = now()
9
+
-- "2026-04-19T15:30:00Z"
10
+
```
11
+
12
+
Returns the current UTC time as an ISO 8601 string. Use this for `createdAt`, `updatedAt`, and similar timestamp fields.
13
+
14
+
## log
15
+
16
+
```lua
17
+
log("processing record: " .. uri)
18
+
log("count: " .. tostring(n))
19
+
```
20
+
21
+
Writes a message to the server logs at debug level. Useful for debugging scripts during development. Log output appears in HappyView's stdout — check your platform's log viewer (Railway logs, `docker logs`, terminal output) to see it.
22
+
23
+
## TID
24
+
25
+
```lua
26
+
local id = TID()
27
+
-- "3abc123def456"
28
+
```
29
+
30
+
Generates a fresh atproto TID (Timestamp Identifier) — a 13-character, base32-sortable string derived from the current timestamp. TIDs are the standard record key format in atproto. Use this when creating records with a specific rkey:
31
+
32
+
```lua
33
+
local r = Record(collection, { text = "hello" })
34
+
r:set_rkey(TID())
35
+
r:save()
36
+
```
37
+
38
+
## toarray
39
+
40
+
```lua
41
+
return { items = toarray(results) }
42
+
```
43
+
44
+
Marks a Lua table so it serializes as a JSON array rather than a JSON object. This matters for empty tables — without `toarray`, an empty `{}` becomes a JSON object `{}` instead of an array `[]`.
45
+
46
+
```lua
47
+
-- Without toarray:
48
+
return { items = {} }
49
+
-- → {"items": {}}
50
+
51
+
-- With toarray:
52
+
return { items = toarray({}) }
53
+
-- → {"items": []}
54
+
```
55
+
56
+
You don't need `toarray()` on results from `db.query`, `db.search`, `db.backlinks`, or `db.raw` — those already return properly marked arrays. Use it when you build a table yourself with `table.insert()` or array-index assignment.