Skip to content

Commit 00ca158

Browse files
mattjohnsonpintmattjohnsonpint
committed
Add localtime docs
1 parent e57415f commit 00ca158

File tree

5 files changed

+290
-3
lines changed

5 files changed

+290
-3
lines changed

‎mint.json‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -133,7 +133,10 @@
133133
},
134134
{
135135
"group": "System APIs",
136-
"pages": ["modus/sdk/assemblyscript/console"]
136+
"pages": [
137+
"modus/sdk/assemblyscript/console",
138+
"modus/sdk/assemblyscript/localtime"
139+
]
137140
}
138141
]
139142
},
@@ -163,7 +166,7 @@
163166
},
164167
{
165168
"group": "System APIs",
166-
"pages": ["modus/sdk/go/console"]
169+
"pages": ["modus/sdk/go/console", "modus/sdk/go/localtime"]
167170
}
168171
]
169172
}

‎modus/sdk/assemblyscript/localtime.mdx‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
title: Local Time
3+
description: "Access the user's local time and time zone in your functions"
4+
---
5+
6+
import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx"
7+
8+
<SdkHeader language="AssemblyScript" feature="Local Time" />
9+
10+
The Modus Local Time APIs allow you to access the user's local time and time
11+
zone from your functions.
12+
13+
## Import
14+
15+
To begin, import the `localtime` namespace from the SDK:
16+
17+
```ts
18+
import { localtime } from "@hypermode/modus-sdk-as"
19+
```
20+
21+
{/* <!-- vale Google.Headings = NO --> */}
22+
23+
## Local Time APIs
24+
25+
The APIs in the `localtime` namespace are below.
26+
27+
All time zones use the IANA time zone database format. For example,
28+
`"America/New_York"`. You can find a list of valid time zones
29+
[here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
30+
31+
<Info>
32+
33+
{/* <!-- vale Google.Passive = NO --> */}
34+
35+
For APIs that work with the user's local time, the time zone is determined in
36+
the following order of precedence:
37+
38+
- If the `X-Time-Zone` header is present in the request, the time zone is set to
39+
the value of the header.
40+
- If the `TZ` environment variable is set on the host, the time zone is set to
41+
the value of the variable.
42+
- Otherwise, the time zone is set to the host's local time zone.
43+
44+
{/* <!-- vale Google.Passive = YES --> */}
45+
46+
</Info>
47+
48+
<Tip>
49+
50+
When working locally with `modus dev`, Modus uses the host's local time zone by
51+
default. You can override this by setting the `TZ` environment variable in your
52+
`.env.local` file.
53+
54+
</Tip>
55+
56+
<Tip>
57+
58+
In a browser-based web app, you can get the user's time zone with the following
59+
JavaScript code:
60+
61+
```js
62+
const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone
63+
```
64+
65+
Assign that value to a `"X-Time-Zone"` request header when calling Modus, to use
66+
it for all local time calculations.
67+
68+
</Tip>
69+
70+
<Tip>
71+
72+
If you just need the current UTC time, you can use AssemblyScript's built-in
73+
support:
74+
75+
```ts
76+
const now = new Date(Date.now())
77+
78+
// if you need a string
79+
const utcTime = now.toISOString()
80+
```
81+
82+
</Tip>
83+
84+
<SdkTip />
85+
86+
### Functions
87+
88+
#### getTimeZone
89+
90+
Returns the user's time zone in IANA format.
91+
92+
```ts
93+
function getTimeZone(): string
94+
```
95+
96+
#### isValidTimeZone
97+
98+
Determines whether the specified time zone is a valid IANA time zone and
99+
recognized by the system as such.
100+
101+
```ts
102+
function isValidTimeZone(tz: string): bool
103+
```
104+
105+
<ResponseField name="tz" type="string" required>
106+
An IANA time zone identifier, such as `"America/New_York"`.
107+
</ResponseField>
108+
109+
#### now
110+
111+
Returns the current local time in the user's time zone, as a string in ISO 8601
112+
extended format, including the applicable time zone offset.
113+
114+
For example, `"2025-12-31T12:34:56.789-04:00"`.
115+
116+
```ts
117+
function now(): string
118+
```
119+
120+
#### nowInZone
121+
122+
Returns the current local time in a specified time zone, as a string in ISO 8601
123+
extended format, including the applicable time zone offset.
124+
125+
For example, `"2025-12-31T12:34:56.789-04:00"`.
126+
127+
```ts
128+
function nowInZone(tz: string): string
129+
```
130+
131+
<ResponseField name="tz" type="string" required>
132+
An IANA time zone identifier, such as `"America/New_York"`.
133+
</ResponseField>

‎modus/sdk/go/localtime.mdx‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
title: Local Time
3+
description: "Access the user's local time and time zone in your functions"
4+
---
5+
6+
import { SdkHeader, SdkTip } from "/snippets/sdk-snippets.mdx"
7+
8+
<SdkHeader language="Go" feature="Local Time" />
9+
10+
The Modus Local Time APIs allow you to access the user's local time and time
11+
zone from your functions.
12+
13+
## Import
14+
15+
To begin, import the `localtime` package from the SDK:
16+
17+
```go
18+
import github.com/hypermodeinc/modus/sdk/go/pkg/localtime
19+
```
20+
21+
{/* <!-- vale Google.Headings = NO --> */}
22+
23+
## Local Time APIs
24+
25+
The APIs in the `localtime` package are below.
26+
27+
All time zones use the IANA time zone database format. For example,
28+
`"America/New_York"`. You can find a list of valid time zones
29+
[here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
30+
31+
<Info>
32+
33+
{/* <!-- vale Google.Passive = NO --> */}
34+
35+
For APIs that work with the user's local time, the time zone is determined in
36+
the following order of precedence:
37+
38+
- If the `X-Time-Zone` header is present in the request, the time zone is set to
39+
the value of the header.
40+
- If the `TZ` environment variable is set on the host, the time zone is set to
41+
the value of the variable.
42+
- Otherwise, the time zone is set to the host's local time zone.
43+
44+
{/* <!-- vale Google.Passive = YES --> */}
45+
46+
</Info>
47+
48+
<Tip>
49+
50+
When working locally with `modus dev`, Modus uses the host's local time zone by
51+
default. You can override this by setting the `TZ` environment variable in your
52+
`.env.local` file.
53+
54+
</Tip>
55+
56+
<Tip>
57+
58+
In a browser-based web app, you can get the user's time zone with the following
59+
JavaScript code:
60+
61+
```js
62+
const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone
63+
```
64+
65+
Assign that value to a `"X-Time-Zone"` request header when calling Modus, to use
66+
it for all local time calculations.
67+
68+
</Tip>
69+
70+
<Tip>
71+
72+
In many cases, you can use Go's built-in time support:
73+
74+
```go
75+
// to get the current time in UTC
76+
now := time.Now().UTC()
77+
78+
// if you need a string
79+
s := now.Format(time.RFC3339)
80+
```
81+
82+
</Tip>
83+
84+
<Warning>
85+
86+
Due to Go's WASM implementation, the standard `time.Now()` function always
87+
returns the UTC time, not the user's local time like it usually does in Go. If
88+
you need the user's local time, use `localtime.Now()` instead.
89+
90+
</Warning>
91+
92+
<SdkTip />
93+
94+
### Functions
95+
96+
#### GetLocation
97+
98+
Returns a pointer to a Go `time.Location` object for a specific time zone.
99+
Errors if the time zone provided is invalid.
100+
101+
```go
102+
func GetLocation(tz string) (*time.Location, error)
103+
```
104+
105+
#### GetTimeZone
106+
107+
Returns the user's time zone in IANA format.
108+
109+
```go
110+
func GetTimeZone() string
111+
```
112+
113+
#### IsValidTimeZone
114+
115+
Determines whether the specified time zone is a valid IANA time zone and
116+
recognized by the system as such.
117+
118+
```go
119+
func IsValidTimeZone(tz string) bool
120+
```
121+
122+
<ResponseField name="tz" type="string" required>
123+
An IANA time zone identifier, such as `"America/New_York"`.
124+
</ResponseField>
125+
126+
#### Now
127+
128+
Returns the current time as a `time.Time` object, with the location set to the
129+
user's local time zone. Errors if the time zone passed to the host is invalid.
130+
131+
```go
132+
func Now() (time.Time, error)
133+
```
134+
135+
#### NowInZone
136+
137+
Returns the current time as a `time.Time` object, with the location set to a
138+
specific time zone. Errors if the time zone provided is invalid.
139+
140+
```go
141+
func NowInZone(tz string) (time.Time, error)
142+
```
143+
144+
<ResponseField name="tz" type="string" required>
145+
An IANA time zone identifier, such as `"America/New_York"`.
146+
</ResponseField>

‎snippets/sdk-snippets.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,15 @@ export const SdkHeader = ({language, feature}) => (
55
<ul>
66
{(() =>{
77
const languages = ["AssemblyScript", "Go"];
8+
const page = feature.toLowerCase().replace(/\W/g, "");
89
return languages.map((lang) => {
910
if (lang === language) {
1011
return (
1112
<li><b>{lang} {feature} APIs</b> (this page)</li>
1213
)
1314
} else {
1415
return (
15-
<li><a href={`../${lang.toLowerCase()}/${feature.toLowerCase()}`}>{lang} {feature} APIs</a></li>
16+
<li><a href={`../${lang.toLowerCase()}/${page}`}>{lang} {feature} APIs</a></li>
1617
)
1718
}
1819
})

‎styles/config/vocabularies/general/accept.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,9 @@ GraphQL|graphql
5555
gRPC
5656
HTTP|http
5757
Hugging Face
58+
IANA
5859
Infof
60+
ISO
5961
LLM
6062
Logf
6163
MySQL|mysql
@@ -69,6 +71,8 @@ Scattergories
6971
SDK|sdk
7072
TLS
7173
URL|url
74+
UTC
7275
urql
7376
UUID
7477
Warnf
78+
WASM

0 commit comments

Comments
 (0)