fetch#

The fetch() method initiates an HTTP/HTTPS network request and returns a Promise that resolves to a Response object. It behaves similarly to the standard Fetch API available in browsers but includes native extensions optimized for Scripting’s iOS runtime environment — such as local file access, Data integration, custom redirect handling, abort control, and debugging labels.

Definition#

1function fetch(url: string, init?: RequestInit): Promise<Response>
2function fetch(request: Request): Promise<Response>

Parameters#

1. url: string#

The URL to request. It can be:

• A network resource, e.g. "https://api.example.com/data"
• A local file URL, e.g. "file:///var/mobile/Containers/Data/Application/..."

2. init?: RequestInit#

An optional configuration object used to customize the request’s method, headers, body, timeout, abort signal, and other options.

1type RequestInit = {
2  method?: string;
3  headers?: HeadersInit;
4  body?: Data | FormData | string | ArrayBuffer;
5  allowInsecureRequest?: boolean;
6  handleRedirect?: (newRequest: RedirectRequest) => Promise<RedirectRequest | null>;
7  shouldAllowRedirect?: (newRequest: Request) => Promise<boolean>; // deprecated
8  timeout?: number; // seconds
9  signal?: AbortSignal;
10  cancelToken?: CancelToken; // deprecated
11  debugLabel?: string;
12}

Parameter Details#

Return Value#

Returns a Promise<Response>.

The Response object represents the result of the request. Even when the HTTP status code indicates failure (e.g., 404 or 500), fetch resolves successfully with a Response. The Promise is rejected only when:

• The request cannot be completed (e.g., network error)
• The URL is malformed
• The request is aborted or times out

Error Handling#

Examples#

Example 1 — Basic GET Request#

1const response = await fetch("https://api.example.com/data")
2if (response.ok) {
3  const json = await response.json()
4  console.log(json)
5} else {
6  console.log("Request failed:", response.status)
7}

Example 2 — POST Request with JSON Body#

1const response = await fetch("https://api.example.com/posts", {
2  method: "POST",
3  headers: { "Content-Type": "application/json" },
4  body: JSON.stringify({ title: "Hello", content: "World" }),
5})
6const result = await response.json()
7console.log(result)

Example 3 — Uploading Files via FormData#

1const form = new FormData()
2form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "image.png")
3form.append("user", "Tom")
4
5const response = await fetch("https://api.example.com/upload", {
6  method: "POST",
7  body: form,
8})
9console.log(await response.json())

Example 4 — Timeout Handling#

1try {
2  const response = await fetch("https://example.com/slow", { timeout: 10 })
3  const text = await response.text()
4  console.log(text)
5} catch (err) {
6  if (err.name === "AbortError") {
7    console.log("Request aborted due to timeout")
8  }
9}

Example 5 — Aborting Requests with AbortController#

1const controller = new AbortController()
2
3setTimeout(() => {
4  controller.abort("User cancelled the request")
5}, 3000)
6
7try {
8  const response = await fetch("https://example.com/large", { signal: controller.signal })
9  const data = await response.text()
10  console.log(data)
11} catch (err) {
12  if (err.name === "AbortError") {
13    console.log("Request was manually aborted")
14  }
15}

Example 6 — Custom Redirect Handling#

1const response = await fetch("https://example.com/redirect", {
2  handleRedirect: async (newRequest) => {
3    console.log("Redirect detected:", newRequest.url)
4    if (newRequest.url.includes("forbidden")) {
5      return null // Cancel redirect
6    }
7    return newRequest // Allow redirect
8  },
9})

Example 7 — Debug Label for Logging#

1await fetch("https://api.example.com/status", {
2  debugLabel: "Health Check",
3})
4// The request will be labeled "Health Check" in the log panel

Relationship with Other Classes#

Additional Details#

• Cookie Management: fetch does not automatically store or send cookies. Cookies from responses can be accessed via response.cookies.

• Redirects: Redirects are automatically followed unless overridden by handleRedirect.

• Concurrency: Each request runs independently and safely in parallel.

• File Support: You can upload local files using Data.fromFile() as the request body.

Summary#

The fetch() API in Scripting extends the standard web Fetch interface with native capabilities:

• Full iOS-native networking integration
• Support for Data binary objects
• File upload and download handling
• Timeout and abort control
• Custom redirect interception
• Local logging with debugLabel