Hello

Welcome

This is a simple Scripting HTTP server.

Partial Content

``` Loads a `UIImage` object. - Suitable for lightweight display - Not intended for file-level processing or asset preservation *** ### loadLivePhoto ```ts loadLivePhoto(): Promise ``` Loads a `LivePhoto` object. - Includes both the still image and paired video - Suitable for display, saving, or further processing *** ### loadURL ```ts loadURL(): Promise ``` Loads a URL and returns it as a string. - May represent a web URL or a file URL *** ### loadText ```ts loadText(): Promise ``` Loads plain text content. - Supports plain text - Rich text is automatically converted to plain text *** ### loadData ```ts loadData(type: UTType): Promise ``` Loads raw binary data for the specified type. - The entire data payload is loaded into memory - Suitable for JSON, configuration files, or small resources - Not recommended for large files such as video or audio *** ## File Path Loading and Security Scope Access to file paths is subject to strict security rules. All file access must occur within a limited callback scope provided by the API. *** ### loadFilePath ```ts loadFilePath(type: UTType): Promise ``` Loads a file path for the specified type. If the item provider can load data as the specified type, this file will be copied to the app group's temporary directory and the file path will be returned, otherwise null will be returned. You should delete the file when it is no longer needed. Example: ```ts const filePath = provider.loadFilePath("public.movie") ``` *** ## Creating an ItemProvider ### fromUIImage ```ts ItemProvider.fromUIImage(image: UIImage): ItemProvider ``` Creates an `ItemProvider` from a `UIImage`. - Provides static image capabilities only - Does not include Live Photo or original asset information *** ### fromText ```ts ItemProvider.fromText(text: string): ItemProvider ``` Creates an `ItemProvider` from a text string. *** ### fromURL ```ts ItemProvider.fromURL(url: string): ItemProvider | null ``` Creates an `ItemProvider` from a URL string. - Returns `null` if the URL is invalid - Supports both web URLs and file URLs *** ### fromFilePath ```ts ItemProvider.fromFilePath(path: string): ItemProvider ``` Creates an `ItemProvider` from a file path. - Preserves the original file - Suitable for videos, audio, and documents - Supports open-in-place capability checks *** ## Usage Guidelines - Use `hasItemConforming` to determine content categories - Use object loading methods for UI display - Use file path loading methods for large resources - Always access files only within the provided callback scope - Never defer access to security-scoped files outside the callback --- url: /doc_v2/guide/Utilities/OAuth2.md --- # OAuth2 The `OAuth2` class provides a robust interface for managing OAuth 2.0 authorization flows in Scripting. It supports standard authorization code flows, PKCE (Proof Key for Code Exchange), access token renewal, and customizable token handling. *** ## Constructor ```ts new OAuth2(options: { consumerKey: string consumerSecret: string authorizeUrl: string accessTokenUrl?: string responseType: string contentType?: string }) ``` ### Parameters | Name | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------------------------------------------------------- | | consumerKey | string | Yes | The application's client ID or consumer key. | | consumerSecret | string | Yes | The application's client secret. | | authorizeUrl | string | Yes | The URL where the user will be redirected for authorization. | | accessTokenUrl | string | No | The endpoint to request the access token. If omitted, `authorizeUrl` is used. | | responseType | string | Yes | Typically `"code"` for the Authorization Code Grant flow. | | contentType | string | No | Content type for token requests. Defaults to `"application/x-www-form-urlencoded"`. | ### Throws - Error if the configuration is invalid or instantiation fails. *** ## Properties ### `accessTokenBasicAuthentification: boolean` Enable this to use HTTP Basic authentication when exchanging the authorization code for an access token. Default is `false`. *** ### `allowMissingStateCheck: boolean` Disables CSRF protection based on state parameter validation. **Use with caution.** Default is `false`. *** ### `encodeCallbackURL: boolean` Encodes the callback URL when generating the authorization URL. Required by some providers. Default is `true`. *** ### `encodeCallbackURLQuery: boolean` Controls whether the entire query string is encoded. Some services (e.g., Imgur) require this to be `false`. Default is `true`. *** ## Methods ### `authorize(options): Promise` Initiates the OAuth2 authorization flow, opening a browser window for the user to log in and grant permissions. ```ts authorize(options: { callbackURL?: string scope: string state: string parameters?: Record headers?: Record } & ({ codeVerifier: string codeChallenge: string codeChallengeMethod: string } | { codeVerifier?: never codeChallenge?: never codeChallengeMethod?: never })): Promise ``` #### Parameters | Name | Type | Required | Description | | ------------------- | ----------------------- | ----------- | ------------------------------------------------------------------------------------------- | | callbackURL | string | No | Custom redirect URI. Default is `scripting://oauth_callback/{current_script_encoded_name}`. | | scope | string | Yes | Space-separated list of requested scopes. | | state | string | Yes | A unique string used to prevent CSRF attacks. | | parameters | Record\ | No | Extra query parameters to send in the authorization request. | | headers | Record\ | No | Extra headers to send in the request. | | codeVerifier | string | Conditional | Raw random string used in PKCE flow. | | codeChallenge | string | Conditional | Hashed version of the code verifier. | | codeChallengeMethod | "plain" \| "S256" | Conditional | Hashing method for code challenge. Default is `"S256"`. | #### Returns - A Promise that resolves to an `OAuthCredential` object containing tokens and metadata. #### Throws - Error if the user denies authorization or a network/response error occurs. #### Example ```ts const oauth = new OAuth2({ consumerKey: 'your-client-id', consumerSecret: 'your-client-secret', authorizeUrl: 'https://provider.com/oauth/authorize', accessTokenUrl: 'https://provider.com/oauth/token', responseType: 'code' }) const credential = await oauth.authorize({ scope: 'profile email', state: 'secure_random_state', callbackURL: Script.createOAuthCallbackURLScheme('my_oauth_script') }) console.log(credential.oauthToken) ``` *** ### `renewAccessToken(options): Promise` Exchanges a refresh token for a new access token from the provider. ```ts renewAccessToken(options: { refreshToken: string parameters?: Record headers?: Record }): Promise ``` #### Parameters | Name | Type | Required | Description | | ------------ | ----------------------- | -------- | -------------------------------------- | | refreshToken | string | Yes | The refresh token previously obtained. | | parameters | Record\ | No | Additional POST body parameters. | | headers | Record\ | No | Additional headers for the request. | #### Returns - A Promise that resolves to an updated `OAuthCredential` object. #### Throws - Error if the refresh fails due to expired or revoked tokens. #### Example ```ts const newCredential = await oauth.renewAccessToken({ refreshToken: previous.oauthRefreshToken }) console.log(newCredential.oauthToken) ``` *** ## OAuthCredential Type The `OAuthCredential` object contains all relevant information from a successful OAuth2 transaction. ```ts type OAuthCredential = { oauthToken: string oauthTokenSecret: string oauthRefreshToken: string oauthTokenExpiresAt: number | null oauthVerifier: string version: string signatureMethod: string } ``` ### Field Descriptions | Field | Type | Description | | ------------------- | -------------- | ---------------------------------------------------------------- | | oauthToken | string | Access token to authorize requests to the API. | | oauthTokenSecret | string | Token secret for request signing (used in OAuth1.0-like flows). | | oauthRefreshToken | string | Token used to refresh the access token. | | oauthTokenExpiresAt | number \| null | Expiration time in Unix timestamp (ms). `null` if no expiration. | | oauthVerifier | string | Verifier used for PKCE validation. | | version | string | OAuth version (e.g., "2.0"). | | signatureMethod | string | Method used to sign requests (e.g., "HMAC-SHA1", "PLAINTEXT"). | *** ## Best Practices - Always verify `state` to protect against CSRF attacks unless explicitly disabled. - Use `Script.createOAuthCallbackURLScheme(name)` to generate script-specific callback URLs. - Securely store the `oauthRefreshToken` if long-term access is needed. - Consider using PKCE for enhanced security, especially in public clients. --- url: /doc_v2/guide/Utilities/Path.md --- # Path The `Path` API provides utility functions for handling and transforming file and directory paths. It is inspired by the Node.js `path` module, offering familiar methods for developers to work with paths effectively. *** ## Overview The `Path` API provides methods for: - Normalizing paths. - Determining if a path is absolute. - Joining path segments. - Extracting path components like directory name, base name, and extension. - Parsing paths into structured objects. It simplifies cross-platform path handling by using the appropriate path delimiters and separators for the current operating system. *** ### Static Methods #### `Path.normalize(path: string): string` Normalizes the given path by resolving `..` and `.` segments. - **Parameters:** - `path`: The input path to normalize. - **Returns:** - A normalized path string. #### Example: ```typescript const normalizedPath = Path.normalize('/foo/bar//baz/asdf/quux/..') console.log(normalizedPath) // '/foo/bar/baz/asdf' ``` *** #### `Path.isAbsolute(path: string): boolean` Determines whether a given path is absolute. - **Parameters:** - `path`: The input path. - **Returns:** - `true` if the path is absolute, otherwise `false`. #### Example: ```typescript console.log(Path.isAbsolute('/foo/bar')) // true console.log(Path.isAbsolute('foo/bar')) // false ``` *** #### `Path.join(...args: string[]): string` Joins multiple path segments into a single path and normalizes it. - **Parameters:** - `...args`: The path segments to join. - **Returns:** - A single normalized path string. #### Example: ```typescript const joinedPath = Path.join('/foo', 'bar', 'baz/asdf', 'quux', '..') console.log(joinedPath) // '/foo/bar/baz/asdf' ``` *** #### `Path.dirname(path: string): string` Returns the directory name of a path. - **Parameters:** - `path`: The input path. - **Returns:** - The directory name. #### Example: ```typescript console.log(Path.dirname('/foo/bar/baz/asdf/quux')) // '/foo/bar/baz/asdf' ``` *** #### `Path.basename(path: string, ext?: string): string` Returns the last portion of a path, similar to the Unix `basename` command. Optionally, removes a file extension. - **Parameters:** - `path`: The input path. - `ext` (optional): The file extension to remove. - **Returns:** - The base name of the path. #### Example: ```typescript console.log(Path.basename('/foo/bar/baz/asdf/quux.html')) // 'quux.html' console.log(Path.basename('/foo/bar/baz/asdf/quux.html', '.html')) // 'quux' ``` *** #### `Path.extname(path: string): string` Returns the extension of the path. - **Parameters:** - `path`: The input path. - **Returns:** - The file extension, or an empty string if none exists. #### Example: ```typescript console.log(Path.extname('/foo/bar/baz/asdf/quux.html')) // '.html' console.log(Path.extname('/foo/bar/baz/asdf/quux')) // '' ``` *** #### `Path.parse(path: string): { root: string; dir: string; base: string; ext: string; name: string; }` Parses a path into an object with the following properties: - `root`: The root of the path. - `dir`: The directory name. - `base`: The file name including the extension. - `ext`: The file extension. - `name`: The file name without the extension. - **Parameters:** - `path`: The input path. - **Returns:** - An object with the parsed path properties. #### Example: ```typescript const parsed = Path.parse('/foo/bar/baz/asdf/quux.html') console.log(parsed) // { // root: '/', // dir: '/foo/bar/baz/asdf', // base: 'quux.html', // ext: '.html', // name: 'quux' // } ``` *** ## Common Use Cases ### Normalize a Path ```typescript const normalizedPath = Path.normalize('./foo/bar/../baz') console.log(normalizedPath) // './foo/baz' ``` ### Check If a Path is Absolute ```typescript console.log(Path.isAbsolute('/absolute/path')) // true console.log(Path.isAbsolute('relative/path')) // false ``` ### Join Multiple Path Segments ```typescript const fullPath = Path.join('/home', 'user', 'documents', 'file.txt') console.log(fullPath) // '/home/user/documents/file.txt' ``` ### Extract File Name and Extension ```typescript const fileName = Path.basename('/path/to/file.txt') const fileExt = Path.extname('/path/to/file.txt') console.log(fileName) // 'file.txt' console.log(fileExt) // '.txt' ``` ### Parse a Path ```typescript const pathDetails = Path.parse('/path/to/file.txt') console.log(pathDetails) // { // root: '/', // dir: '/path/to', // base: 'file.txt', // ext: '.txt', // name: 'file' // } ``` *** ## Best Practices 1. **Use Normalization:** Always normalize paths to ensure consistent formatting across platforms. 2. **Avoid Hardcoding Delimiters:** Use methods like `join` instead of concatenating strings with `/` or `\\`. *** ## Full Example ```typescript import { Path } from 'scripting' function main() { const filePath = '/foo/bar/baz/asdf/quux.html' console.log("Normalized Path:", Path.normalize(filePath)) console.log("Is Absolute:", Path.isAbsolute(filePath)) console.log("Directory Name:", Path.dirname(filePath)) console.log("Base Name:", Path.basename(filePath)) console.log("Extension:", Path.extname(filePath)) const parsedPath = Path.parse(filePath) console.log("Parsed Path:", parsedPath) const joinedPath = Path.join('/foo', 'bar', 'baz') console.log("Joined Path:", joinedPath) } main() ``` --- url: /doc_v2/guide/Utilities/Request/FormData.md --- # FormData The `FormData` class provides a way to construct key/value pairs representing form fields and their values. It is mainly used for building `multipart/form-data` requests that can include both text and binary data (such as files or images). In the **Scripting app**, `FormData` is fully compatible with the standard **Fetch API**, allowing you to send data through `fetch()` with mixed text and file fields. *** ## Definition ```ts class FormData { private formData append(name: string, value: string): void append(name: string, value: Data, mimeType: string, filename?: string): void get(name: string): string | Data | null getAll(name: string): any[] has(name: string): boolean delete(name: string): void set(name: string, value: string): void set(name: string, value: Data, filename?: string): void forEach(callback: (value: any, name: string, parent: FormData) => void): void entries(): [string, any][] toJson(): Record } ``` *** ## Purpose `FormData` is used to: - Build `multipart/form-data` requests with text and file fields. - Upload files (images, documents, audio, etc.) with metadata. - Replace JSON-based bodies when binary data is included. *** ## Methods ### `append(name: string, value: string): void` ### `append(name: string, value: Data, mimeType: string, filename?: string): void` Appends a new field to the form. Can be used to add both text and file fields. #### Parameters | Parameter | Type | Description | | | ------------ | --------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------- | | **name** | `string` | The name of the form field. | | | **value** | `string` | `Data` | The value of the field (text or binary data). | | **mimeType** | `string` | The MIME type of the file (e.g., `"image/png"`). Required only when `value` is a `Data` object. | | | **filename** | `string` _(optional)_ | The filename to include for file uploads. | | #### Example ```tsx const form = new FormData() form.append("username", "Tom") form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "avatar.png") ``` *** ### `set(name: string, value: string): void` ### `set(name: string, value: Data, filename?: string): void` Sets a form field, replacing any existing field with the same name. Unlike `append()`, this overwrites previous values. #### Example ```tsx const form = new FormData() form.set("message", "Hello world") form.set("file", Data.fromFile("/path/to/file.txt"), "text/plain", "note.txt") ``` *** ### `get(name: string): string | Data | null` Retrieves the value of a form field. Returns `null` if the field does not exist. #### Example ```tsx const form = new FormData() form.append("title", "My Post") console.log(form.get("title")) // "My Post" ``` *** ### `getAll(name: string): any[]` Returns all values associated with a given field name (useful when using multiple `append()` calls with the same name). #### Example ```tsx const form = new FormData() form.append("tag", "swift") form.append("tag", "ios") form.append("tag", "scripting") console.log(form.getAll("tag")) // ["swift", "ios", "scripting"] ``` *** ### `has(name: string): boolean` Checks whether a form field exists. #### Example ```tsx const form = new FormData() form.append("username", "Tom") console.log(form.has("username")) // true console.log(form.has("password")) // false ``` *** ### `delete(name: string): void` Deletes the specified field and all of its values. #### Example ```tsx const form = new FormData() form.append("title", "Hello") form.append("file", Data.fromFile("/path/to/file.txt"), "text/plain") form.delete("file") ``` *** ### `forEach(callback: (value: any, name: string, parent: FormData) => void): void` Iterates over all form fields and invokes the callback function for each one. #### Example ```tsx const form = new FormData() form.append("user", "Tom") form.append("age", "25") form.forEach((value, name) => { console.log(`${name}: ${value}`) }) ``` *** ### `entries(): [string, any][]` Returns an array of `[name, value]` pairs for all form fields. #### Example ```tsx const form = new FormData() form.append("username", "Tom") form.append("age", "25") console.log(form.entries()) // [["username", "Tom"], ["age", "25"]] ``` *** ### `toJson(): Record` Converts the form data into a plain JSON object for debugging or logging. If the form contains binary data (`Data` objects), those fields will be represented as descriptive placeholders instead of raw binary data. #### Example ```tsx const form = new FormData() form.append("name", "Tom") form.append("photo", Data.fromFile("/path/to/avatar.png"), "image/png", "avatar.png") console.log(form.toJson()) // { name: "Tom", photo: "[Data: image/png]" } ``` *** ## Usage Examples ### Example 1 — Upload a File ```tsx const form = new FormData() form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "avatar.png") form.append("userId", "1234") const response = await fetch("https://api.example.com/upload", { method: "POST", body: form, }) console.log(await response.json()) ``` *** ### Example 2 — Upload Multiple Files ```tsx const form = new FormData() form.append("files", Data.fromFile("/path/to/photo1.jpg"), "image/jpeg", "photo1.jpg") form.append("files", Data.fromFile("/path/to/photo2.jpg"), "image/jpeg", "photo2.jpg") await fetch("https://api.example.com/multi-upload", { method: "POST", body: form, }) ``` *** ### Example 3 — Mixed Text and File Fields ```tsx const form = new FormData() form.append("title", "Travel Memories") form.append("description", "A collection of travel photos.") form.append("cover", Data.fromFile("/path/to/cover.png"), "image/png", "cover.png") const response = await fetch("https://example.com/uploadPost", { method: "POST", body: form, }) console.log(await response.text()) ``` *** ### Example 4 — Iterating and Debugging ```tsx const form = new FormData() form.append("name", "Alice") form.append("file", Data.fromFile("/path/to/file.txt"), "text/plain", "file.txt") form.forEach((value, name) => { console.log(`${name}:`, value instanceof Data ? "Binary Data" : value) }) ``` *** ## Relationships with Other Classes | Class | Description | | -------------- | ------------------------------------------------------------------------------------------------- | | **`fetch()`** | Accepts `FormData` as a request body; automatically sets `Content-Type` to `multipart/form-data`. | | **`Data`** | Used to represent binary content (e.g., files, images) added to form fields. | | **`Request`** | A `FormData` instance can be passed to `RequestInit.body`. | | **`Response`** | You can use `response.formData()` to parse a multipart response into a `FormData` object. | *** ## Notes - **Automatic Content-Type:** When you pass a `FormData` instance to `fetch()`, the app automatically sets the correct `Content-Type` header (with a boundary). Do not manually set it. - **Multiple Fields:** Use `append()` to add multiple values with the same name. - **Binary Uploads:** Always provide a MIME type for binary uploads. Otherwise, the data defaults to `application/octet-stream`. - **JSON Conversion:** The `toJson()` method is intended for debugging and should not be used for actual data transmission. *** ## Summary `FormData` is the **core class for building multipart/form-data requests** in the Scripting app. It provides a flexible and developer-friendly API for combining text and binary fields, integrating seamlessly with `fetch()` and `Data`. ### Key Features - Fully compatible with the Fetch API - Supports text and file uploads - Automatically handles multipart boundaries - Useful debugging utilities (`entries()`, `toJson()`) - Integrates natively with `Data`, `Request`, and `Response` --- url: /doc_v2/guide/Utilities/Request/Headers.md --- # Headers The `Headers` class represents a collection of HTTP request or response header fields. It is fully compatible with the **Fetch API** standard but includes additional convenience methods for scripting environments, such as JSON conversion for debugging and serialization. A `Headers` object can be used in the following contexts: - When creating a request via `RequestInit.headers` - When reading headers from a `Response` object - When programmatically modifying header data in a script *** ## Definition ```ts class Headers { constructor(init?: HeadersInit) append(name: string, value: string): void get(name: string): string | null has(name: string): boolean set(name: string, value: string): void delete(name: string): void forEach(callback: (value: string, name: string) => void): void keys(): string[] values(): string[] entries(): [string, string][] toJson(): Record } ``` *** ## HeadersInit Type `Headers` can be initialized using multiple formats: ```ts type HeadersInit = [string, string][] | Record | Headers ``` You can create a `Headers` object using any of these forms: ```tsx new Headers([["Content-Type", "application/json"]]) new Headers({ "Authorization": "Bearer token" }) new Headers(existingHeaders) ``` *** ## Constructor ### `new Headers(init?: HeadersInit)` Creates a new `Headers` instance. You can optionally pass initial header data. #### Parameters | Parameter | Type | Description | | --------- | ------------- | ---------------------------------------------------------------------------- | | **init** | `HeadersInit` | Initial header data. Can be an object, array, or another `Headers` instance. | *** ## Methods ### `append(name: string, value: string): void` Adds a new value to an existing header field. If the field already exists, the new value is **appended** instead of replacing the old one. #### Example ```tsx const headers = new Headers() headers.append("Accept", "application/json") headers.append("Accept", "text/plain") // Now "Accept" has two values ``` *** ### `set(name: string, value: string): void` Sets a header field to a specific value. If the field already exists, it will be **overwritten**. #### Example ```tsx const headers = new Headers() headers.set("Content-Type", "application/json") headers.set("Authorization", "Bearer token-123") ``` *** ### `get(name: string): string | null` Retrieves the value of a specific header field. Returns `null` if the field does not exist. #### Example ```tsx const headers = new Headers({ "Content-Type": "application/json" }) console.log(headers.get("Content-Type")) // "application/json" ``` *** ### `has(name: string): boolean` Checks whether a specific header field exists. #### Example ```tsx const headers = new Headers({ "Accept": "application/json" }) console.log(headers.has("Accept")) // true console.log(headers.has("Authorization")) // false ``` *** ### `delete(name: string): void` Removes a specific header field. #### Example ```tsx const headers = new Headers({ "Accept": "application/json", "Cache-Control": "no-cache" }) headers.delete("Cache-Control") ``` *** ### `forEach(callback: (value: string, name: string) => void): void` Iterates over all header fields and executes the callback for each pair. #### Example ```tsx const headers = new Headers({ "Accept": "application/json", "User-Agent": "ScriptingApp/1.0" }) headers.forEach((value, name) => { console.log(`${name}: ${value}`) }) ``` *** ### `keys(): string[]` Returns an array containing all header names. ```tsx const headers = new Headers({ "Accept": "application/json", "User-Agent": "Scripting" }) console.log(headers.keys()) // ["accept", "user-agent"] ``` > Note: Header names are **case-insensitive** and normalized to lowercase. *** ### `values(): string[]` Returns an array containing all header values. ```tsx const headers = new Headers({ "Accept": "application/json", "User-Agent": "Scripting" }) console.log(headers.values()) // ["application/json", "Scripting"] ``` *** ### `entries(): [string, string][]` Returns an array of `[name, value]` pairs representing all headers. #### Example ```tsx const headers = new Headers({ "Accept": "application/json", "Cache-Control": "no-cache" }) console.log(headers.entries()) // [["accept", "application/json"], ["cache-control", "no-cache"]] ``` *** ### `toJson(): Record` Converts the header collection into a plain JSON object for easy serialization and debugging. #### Example ```tsx const headers = new Headers({ "Content-Type": "application/json", "Authorization": "Bearer token" }) console.log(headers.toJson()) // { "content-type": "application/json", "authorization": "Bearer token" } ``` *** ## Usage Examples ### Example 1 — Setting Custom Headers in a Request ```tsx const headers = new Headers() headers.set("Content-Type", "application/json") headers.set("Authorization", "Bearer token-xyz") const response = await fetch("https://api.example.com/user", { method: "POST", headers, body: JSON.stringify({ name: "Tom" }), }) ``` *** ### Example 2 — Reading Response Headers ```tsx const response = await fetch("https://example.com/data") console.log("Content-Type:", response.headers.get("Content-Type")) console.log("Server:", response.headers.get("Server")) ``` *** ### Example 3 — Converting to JSON for Logging ```tsx const response = await fetch("https://example.com/api") console.log("Response Headers:", response.headers.toJson()) ``` *** ### Example 4 — Checking for Specific Headers ```tsx const response = await fetch("https://example.com/info") if (response.headers.has("Set-Cookie")) { console.log("The response contains a Set-Cookie header") } ``` *** ## Relationships with Other Classes | Class | Description | | -------------- | ---------------------------------------------------------------------------------------- | | **`Request`** | Headers can be defined in `RequestInit.headers` when creating requests. | | **`Response`** | Access response headers via `response.headers`. | | **`fetch()`** | Both requests and responses use `Headers` to manage header data. | | **`Cookie`** | Cookies returned in headers can be parsed into structured objects in `response.cookies`. | *** ## Notes - **Case-insensitivity:** Header names are case-insensitive and stored in lowercase form. - **Multi-value headers:** Use `append()` to add multiple values for the same header (e.g., for `Accept` or `Cookie`). - **System headers:** Certain system-managed headers (e.g., `Host`, `Connection`) may be ignored or overwritten by the iOS networking stack. - **Serialization:** The `toJson()` method is useful for logging, debugging, or serializing header data. *** ## Summary The `Headers` class is a foundational component of the **Scripting networking system**, providing a consistent and convenient interface for managing HTTP headers. It enables developers to: - Add, modify, and remove headers dynamically - Read and iterate through response headers - Work with both request and response headers in a unified way - Output structured header data for logging and debugging --- url: /doc_v2/guide/Utilities/Request/ReadableStream.md --- # ReadableStream `ReadableStream` represents a **stream of data** that can be read incrementally rather than all at once. In **Scripting**, `ReadableStream` is used in various scenarios, including: - Handling **streaming HTTP responses** (e.g., `Response.body`) - **Chunked file downloads** or large data transfers - **Real-time data streams** such as logs, AI model output, or event streams It follows the same behavior as the standard **Web Streams API**, allowing asynchronous iteration (`for await...of`) and manual reading via a `ReadableStreamDefaultReader`. *** ## Definition ```ts class ReadableStream { constructor(underlyingSource?: UnderlyingSource) get locked(): boolean cancel(reason?: any): Promise getReader(): ReadableStreamDefaultReader tee(): [ReadableStream, ReadableStream] } ``` *** ## Overview - A `ReadableStream` represents a **data source that can be consumed asynchronously**. - Instead of loading the entire payload into memory, data is read **in chunks** as it becomes available. - Only one active reader can consume a stream at a time. When locked (`locked = true`), no other consumer can access it until released or canceled. *** ## Properties ### `locked: boolean` Indicates whether the stream is currently locked to a reader. If `true`, you must release the lock or cancel the stream before another reader can be created. #### Example ```tsx const reader = response.body.getReader() console.log(response.body.locked) // true ``` *** ## Methods ### `getReader(): ReadableStreamDefaultReader` Returns a `ReadableStreamDefaultReader` that allows manual, incremental reading of stream data. Each call to `reader.read()` returns a Promise resolving to an object `{ value, done }`. #### Example ```tsx const reader = response.body.getReader() while (true) { const { done, value } = await reader.read() if (done) break console.log("Received chunk:", value) } ``` *** ### `cancel(reason?: any): Promise` Cancels reading from the stream. Optionally provide a `reason` describing why the operation was aborted. #### Example ```tsx const reader = response.body.getReader() await response.body.cancel("User canceled reading") ``` *** ### `tee(): [ReadableStream, ReadableStream]` Splits a stream into two identical branches that can be consumed independently. #### Example ```tsx const [stream1, stream2] = response.body.tee() const reader1 = stream1.getReader() const reader2 = stream2.getReader() ``` *** ## ReadableStreamDefaultReader When you obtain a reader using `getReader()`, you can manually control the reading process. ### Definition ```ts interface ReadableStreamDefaultReader { read(): Promise<{ value: T; done: boolean }> releaseLock(): void cancel(reason?: any): Promise } ``` #### Method Descriptions | Method | Description | | ------------------- | ----------------------------------------------------------------------------------------------------- | | **read()** | Reads the next data chunk. Resolves with `{ value, done }`. When `done = true`, the stream has ended. | | **releaseLock()** | Releases the lock so the stream can be read again by another consumer. | | **cancel(reason?)** | Cancels reading from the stream. | #### Example — Reading Stream Data ```tsx const reader = response.body.getReader() while (true) { const { done, value } = await reader.read() if (done) break // Each chunk is a Data instance const text = value.toRawString() console.log("Chunk:", text) } reader.releaseLock() ``` *** ## Integration with Response The `Response.body` property is a `ReadableStream` that allows streaming response content. #### Example — Handling Streaming Network Response ```tsx const response = await fetch("https://example.com/stream") const reader = response.body.getReader() while (true) { const { done, value } = await reader.read() if (done) break console.log("Received:", value.toRawString()) } ``` This method enables real-time data processing **before the full response is received**, ideal for: - Real-time log streaming - Progressive file downloads - AI or LLM text generation (token streaming) *** ## Integration with Data In Scripting, each stream chunk (`value`) is a `Data` object. You can use the `Data` APIs such as `.toRawString()` or `.toUint8Array()` to inspect or transform the content. #### Example — Save Stream Data to a File ```tsx const reader = response.body.getReader() const chunks: Data[] = [] while (true) { const { done, value } = await reader.read() if (done) break chunks.push(value) } const fileData = Data.combine(chunks) FileManager.write(fileData, "/local/download.bin") ``` *** ## Using Async Iteration `ReadableStream` supports async iteration (`for await...of`), simplifying data consumption syntax: ```tsx for await (const chunk of response.body) { console.log("Chunk size:", chunk.size) } ``` This approach automatically handles the `done` condition for you, resulting in cleaner code. *** ## Common Use Cases | Use Case | Example | | -------------------------------- | ------------------------------------------------------------------------------- | | **Large File Download** | Stream file chunks from the network and save locally without high memory usage. | | **AI Output Streaming** | Display real-time model output as it’s generated. | | **Incremental Local Processing** | Process local files or streams incrementally. | *** ## Notes - **Single-reader rule:** Only one reader can consume a `ReadableStream` at a time. - **Memory efficiency:** Streaming avoids loading large payloads entirely into memory. - **Error handling:** Reading may reject on errors (e.g., network failure). Use `try...catch` to handle exceptions safely. - **Chunk type:** For `Response.body`, each chunk is a `Data` object — not plain text or byte arrays. *** ## Summary `ReadableStream` is a **core component of Scripting’s streaming data architecture**, providing efficient and flexible data handling capabilities. ### Key Features - Asynchronous, incremental data reading - Seamless integration with `fetch()`, `Response`, and `Data` - Supports real-time processing and large data transfers - Fully compatible with the standard **Web Streams API** --- url: /doc_v2/guide/Utilities/Request/Request & RequestInit.md --- # Request & RequestInit The `Request` class represents a complete configuration of an HTTP request. It can be passed directly to the `fetch()` method or used to clone, modify, or retry an existing request. In Scripting, the `Request` API behaves similarly to the browser’s Fetch API but adds native extensions, including: - Binary `Data` type support for request bodies - Custom redirect handling - Request timeout and cancellation - Optional allowance for insecure (HTTP) requests - Debug labels for internal logging *** ## Definition ```ts class Request { url: string; method: string; headers: Headers; body?: Data | FormData | string | ArrayBuffer; allowInsecureRequest?: boolean; handleRedirect?: (newRequest: RedirectRequest) => Promise; shouldAllowRedirect?: (newRequest: Request) => Promise; // deprecated timeout?: DurationInSeconds; signal?: AbortSignal; cancelToken?: CancelToken; // deprecated debugLabel?: string; constructor(input: string | Request, init?: RequestInit); clone(): Request; } ``` *** ## Constructor ### `new Request(input: string | Request, init?: RequestInit)` Creates a new `Request` instance from either a URL string or an existing `Request` object. #### Parameters \| Parameter | Type | Description | \| --------- | ------------- | -------------------------------------------------------------------- | ------------------------------------------------ | \| **input** | `string` | `Request` | The target URL, or an existing request to clone. | \| **init** | `RequestInit` | Optional configuration object defining request settings (see below). | *** ## Properties | Property | Type | Description | | ------------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | **url** | `string` | The full URL of the request. | | **method** | `string` | The HTTP method (default is `"GET"`). | | **headers** | `Headers` | A headers object representing the request headers. | | **body** | `Data` \| `FormData` \| `string` \| `ArrayBuffer` \| `undefined` | The request body, used only for non-`GET` and non-`HEAD` requests. | | **allowInsecureRequest** | `boolean` | Whether to allow plain HTTP requests (default `false`). | | **handleRedirect** | `(newRequest: RedirectRequest) => Promise` | Custom redirect handler. Return `null` to cancel the redirect. | | **shouldAllowRedirect** | `(newRequest: Request) => Promise` | Deprecated legacy redirect handler. | | **timeout** | `number` | Timeout in seconds. The request will automatically abort after this duration. | | **signal** | `AbortSignal` | Abort signal from an `AbortController`, allowing manual cancellation. | | **cancelToken** | `CancelToken` | Deprecated. Older cancellation mechanism; prefer `signal`. | | **debugLabel** | `string` | Optional label displayed in logs for debugging and tracking requests. | *** ## Methods ### `clone(): Request` Creates and returns a copy of the current request. The cloned object can be safely modified (e.g., updating headers or timeout) without affecting the original request. #### Example ```tsx const req1 = new Request("https://api.example.com/user", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ name: "Alice" }), }); const req2 = req1.clone(); console.log(req2.method); // "POST" ``` *** ## Examples ### Example 1 — Creating a Simple Request ```tsx const request = new Request("https://api.example.com/data", { method: "GET", headers: { Accept: "application/json", }, debugLabel: "Fetch User Data", }); const response = await fetch(request); const result = await response.json(); console.log(result); ``` *** ### Example 2 — POST Request with a Body ```tsx const request = new Request("https://api.example.com/upload", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ fileId: "abc123" }), timeout: 15, }); const response = await fetch(request); console.log(await response.text()); ``` *** ### Example 3 — Cloning and Modifying a Request ```tsx const base = new Request("https://api.example.com/posts", { method: "POST", headers: { "Content-Type": "application/json" }, }); const cloned = base.clone(); cloned.headers.set("Authorization", "Bearer token-123"); cloned.debugLabel = "Authorized Upload"; await fetch(cloned); ``` *** \##RequestInit Interface The `RequestInit` interface defines configuration options for HTTP requests. It is used as the second argument to `fetch()` or the optional configuration object when creating a new `Request`. Scripting extends this interface with additional native fields. *** ## Definition ```ts type RequestInit = { method?: string; headers?: HeadersInit; body?: Data | FormData | string | ArrayBuffer; allowInsecureRequest?: boolean; handleRedirect?: (newRequest: RedirectRequest) => Promise; shouldAllowRedirect?: (newRequest: Request) => Promise; // deprecated timeout?: DurationInSeconds; signal?: AbortSignal; cancelToken?: CancelToken; // deprecated debugLabel?: string; }; ``` *** ## Field Descriptions | Field | Type | Description | | | ------------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | - | | **method** | `string` | The HTTP method such as `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`. Default: `"GET"`. | | | **headers** | `HeadersInit` | Request headers, which can be a `Headers` object, key-value object `{ key: value }`, or array of `[key, value]` pairs. | | | **body** | `Data` \| `FormData` \| `string` \| `ArrayBuffer` | The request body. Ignored for `GET` and `HEAD` requests. | | | **allowInsecureRequest** | `boolean` | Allows HTTP requests (insecure). Default: `false`. | | | **handleRedirect** | `(newRequest: RedirectRequest) => Promise` | Custom redirect handler. Return `null` to block redirection. | | | **shouldAllowRedirect** | `(newRequest: Request) => Promise` | Deprecated. Older redirect callback. | | | **timeout** | `number` | Request timeout in seconds. Triggers `AbortError` if exceeded. | | | **signal** | `AbortSignal` | Used to abort requests manually through an `AbortController`. | | | **cancelToken** | `CancelToken` | Deprecated cancellation mechanism. Use `signal` instead. | | | **debugLabel** | `string` | A label displayed in the debug log for identifying requests. | | *** ## Relationship with `fetch()` `RequestInit` is typically passed as the second parameter to `fetch()` to configure a network request. ```tsx const response = await fetch("https://example.com/data", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ id: 123 }), timeout: 10, debugLabel: "Upload JSON", }); ``` *** ## Relationships with Other Classes | Class | Description | | ------------------------------------- | -------------------------------------------------------------------------------------- | | **`Headers`** | Manages request headers, used with the `headers` field. | | **`Data`** | Represents binary data. Can be used as the request body for file uploads or raw bytes. | | **`FormData`** | Builds `multipart/form-data` bodies for form or file submissions. | | **`AbortController` / `AbortSignal`** | Enables manual request cancellation. | | **`CancelToken`** | Deprecated cancellation mechanism retained for backward compatibility. | | **`RedirectRequest`** | Represents the redirected request passed to `handleRedirect`. | *** ## Examples ### Example 1 — Custom Redirect Handling ```tsx const response = await fetch("https://example.com/start", { handleRedirect: async (newRequest) => { console.log("Redirect detected:", newRequest.url); if (newRequest.url.includes("blocked")) return null; return newRequest; }, }); ``` *** ### Example 2 — Allowing Insecure Requests ```tsx const response = await fetch("http://insecure.example.com/data", { allowInsecureRequest: true, }); console.log(await response.text()); ``` *** ### Example 3 — Using a Debug Label ```tsx await fetch("https://example.com/api/ping", { debugLabel: "Ping Request", }); // The log panel will display the label "Ping Request" ``` *** ## RedirectRequest Interface When a request encounters an **HTTP redirect**, and a `handleRedirect` callback is defined in the `Request` or `RequestInit` object, the system will invoke that callback before following the redirect. The callback receives a `RedirectRequest` object, which describes the full details of the redirect request. You can inspect or modify this object to control whether and how the redirect should proceed. *** ### Interface Definition ```ts interface RedirectRequest { method: string; url: string; headers: Record; cookies: Cookie[]; body?: Data; timeout?: number; } ``` *** ### Field Descriptions | Field | Type | Description | | ----------- | ------------------------ | ---------------------------------------------------------------------------------------------- | | **method** | `string` | The HTTP method for the redirected request (e.g., `"GET"`, `"POST"`). | | **url** | `string` | The full target URL of the redirect. | | **headers** | `Record` | The HTTP headers to be sent with the redirect request. You can modify these before proceeding. | | **cookies** | `Cookie[]` | The list of cookies available for the redirected request (same format as `Response.cookies`). | | **body** | `Data` _(optional)_ | The body of the redirect request, if applicable (e.g., for non-GET methods). | | **timeout** | `number` _(optional)_ | The request timeout in seconds. | *** ### Use Cases The `handleRedirect` callback allows you to: - Inspect and validate redirect destinations for security or logic reasons. - Modify redirect requests (add headers, update method, or include authorization tokens). - Block unwanted or unsafe redirects. When the callback returns: - A modified `RedirectRequest` → The redirect proceeds using your modified configuration. - `null` → The redirect is **canceled**, and the `fetch()` call resolves with the current response. *** ### Example: Intercepting and Controlling Redirects ```tsx const response = await fetch("https://example.com/start", { handleRedirect: async (redirect) => { console.log("Redirecting to:", redirect.url); // Block redirects to external domains if (!redirect.url.startsWith("https://example.com")) { console.warn("Blocked external redirect:", redirect.url); return null; } // Add authorization header to redirected request redirect.headers["Authorization"] = "Bearer my-token"; return redirect; }, }); ``` *** ### Example: Modifying Redirect Method and Body ```tsx const response = await fetch("https://api.example.com/login", { handleRedirect: async (redirect) => { // Keep the request body when redirecting to a confirmation endpoint if (redirect.url.includes("/finalize")) { redirect.method = "POST"; redirect.body = Data.fromRawString("action=confirm", "utf-8"); } return redirect; }, }); ``` *** ### Notes - If `handleRedirect` is **not defined**, all redirects are automatically followed by default. - Returning `null` from the callback prevents further redirection. - Cookies are **not automatically forwarded**; you can manually inspect and decide whether to reuse cookies from `redirect.cookies`. - Any modifications made to the `RedirectRequest` (such as headers or method) will be applied before the next request is executed. *** ## Summary `Request` and `RequestInit` form the **foundation of Scripting’s networking system**: - `Request` encapsulates a complete HTTP request and can be reused or cloned. - `RequestInit` defines configuration options for flexible initialization. - Together, they integrate tightly with `fetch()`, `Response`, `Headers`, `Data`, and `FormData`. --- url: /doc_v2/guide/Utilities/Request/Response.md --- # Response The `Response` class represents the result of an HTTP request made using the `fetch()` API. It provides access to the response body, headers, cookies, and metadata such as the status code and MIME type. In the **Scripting app**, the `Response` API extends the standard Fetch API behavior to provide **native-level enhancements**, including: - Access to structured cookie data - Binary data handling via the `Data` type - Support for response streaming (`ReadableStream`) - Access to expected content length, MIME type, and text encoding *** ## Definition ```ts class Response { readonly body: ReadableStream get bodyUsed(): boolean get cookies(): Cookie[] json(): Promise text(): Promise data(): Promise bytes(): Promise arrayBuffer(): Promise formData(): Promise get status(): number get statusText(): string get headers(): Headers get ok(): boolean get url(): string get mimeType(): string | undefined get expectedContentLength(): number | undefined get textEncodingName(): string | undefined } ``` *** ## Properties | Property | Type | Description | | | ------------------------- | ---------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------- | | **body** | `ReadableStream` | The response body as a readable stream of `Data` chunks. | | | **bodyUsed** | `boolean` | Indicates whether the response body has been read. | | | **cookies** | `Cookie[]` | A list of cookies sent by the server via the `Set-Cookie` header. | | | **status** | `number` | The HTTP status code of the response (e.g. `200`, `404`, `500`). | | | **statusText** | `string` | The status message returned by the server (e.g. `"OK"`, `"Not Found"`). | | | **headers** | `Headers` | A `Headers` object representing response headers. | | | **ok** | `boolean` | `true` if the status code is between 200 and 299, otherwise `false`. | | | **url** | `string` | The final URL of the response after any redirects. | | | **mimeType** | `string` | `undefined` | The MIME type inferred from headers (e.g. `"application/json"`). | | **expectedContentLength** | `number` | `undefined` | The expected size of the response body in bytes, if provided by the server. | | **textEncodingName** | `string` | `undefined` | The encoding used for text responses (e.g. `"utf-8"`). | *** ## Methods ### `json(): Promise` Parses the response body as JSON. #### Example ```tsx const response = await fetch("https://api.example.com/user") const data = await response.json() console.log(data.name) ``` *** ### `text(): Promise` Reads the response body as a UTF-8 string (or using `textEncodingName` if available). #### Example ```tsx const response = await fetch("https://example.com/message.txt") const text = await response.text() console.log(text) ``` *** ### `data(): Promise` Reads the response body as a binary `Data` object, which can be used for file saving, image decoding, or Base64 conversion. #### Example ```tsx const response = await fetch("https://example.com/image.png") const imageData = await response.data() FileManager.write(imageData, "/local/image.png") ``` *** ### `bytes(): Promise` Reads the response as a byte array (`Uint8Array`). #### Example ```tsx const response = await fetch("https://example.com/file.bin") const bytes = await response.bytes() console.log("Received", bytes.length, "bytes") ``` *** ### `arrayBuffer(): Promise` Reads the response as an `ArrayBuffer`, useful for low-level binary operations. #### Example ```tsx const response = await fetch("https://example.com/file") const buffer = await response.arrayBuffer() console.log(buffer.byteLength) ``` *** ### `formData(): Promise` Parses the response body as form data (for responses with `multipart/form-data` content). #### Example ```tsx const response = await fetch("https://example.com/form") const form = await response.formData() console.log(form.get("username")) ``` *** ### `cookies: Cookie[]` The `cookies` property provides direct access to the cookies set by the server via `Set-Cookie` headers. Each cookie is represented by a `Cookie` object with structured metadata. #### Cookie Type Definition ```ts interface Cookie { name: string value: string domain: string path: string isSecure: boolean isHTTPOnly: boolean isSessionOnly: boolean expiresDate?: Date | null } ``` | Field | Type | Description | | ----------------- | -------------- | ------------------------------------------------------------- | | **name** | `string` | Cookie name. | | **value** | `string` | Cookie value. | | **domain** | `string` | Domain to which the cookie belongs. | | **path** | `string` | Path scope of the cookie. | | **isSecure** | `boolean` | `true` if the cookie is sent only over HTTPS. | | **isHTTPOnly** | `boolean` | `true` if inaccessible to JavaScript. | | **isSessionOnly** | `boolean` | `true` if the cookie is temporary and expires at session end. | | **expiresDate** | `Date \| null` | Expiration date of the cookie, if specified. | #### Example — Reading Cookies ```tsx const response = await fetch("https://example.com/login") for (const cookie of response.cookies) { console.log(`${cookie.name} = ${cookie.value}`) } ``` #### Example — Manual Cookie Management By default, **Scripting’s `fetch()` does not automatically store or send cookies**. To reuse cookies across multiple requests, you can manually include them: ```tsx const response = await fetch("https://example.com/login") const cookies = response.cookies const cookieHeader = cookies.map(c => `${c.name}=${c.value}`).join("; ") const next = await fetch("https://example.com/dashboard", { headers: { "Cookie": cookieHeader }, }) ``` This gives you **explicit cookie control** similar to browser developer tools. *** ## Relationship with Other Classes | Class | Description | | -------------- | -------------------------------------------------------- | | **`Request`** | Represents the HTTP request that produced this response. | | **`Headers`** | Manages response headers. | | **`Data`** | Represents binary data returned from the response body. | | **`FormData`** | Used when the response contains `multipart/form-data`. | | **`Cookie`** | Represents a parsed HTTP cookie object. | *** ## Examples ### Example 1 — Handling JSON API Responses ```tsx const response = await fetch("https://api.example.com/profile") if (response.ok) { const user = await response.json() console.log(user.email) } else { console.log("Error:", response.status, response.statusText) } ``` *** ### Example 2 — Downloading Binary Data ```tsx const response = await fetch("https://example.com/photo.jpg") const fileData = await response.data() FileManager.write(fileData, "/local/photo.jpg") ``` *** ### Example 3 — Reading Cookies from a Response ```tsx const response = await fetch("https://example.com/login") for (const cookie of response.cookies) { console.log(`Cookie: ${cookie.name} = ${cookie.value}`) } ``` *** ### Example 4 — Manual Cookie Persistence Between Requests ```tsx const loginResponse = await fetch("https://example.com/login", { method: "POST", body: JSON.stringify({ username: "Tom", password: "1234" }), headers: { "Content-Type": "application/json" }, }) // Build a cookie header manually const cookieHeader = loginResponse.cookies.map(c => `${c.name}=${c.value}`).join("; ") // Use cookies in a new request const dashboard = await fetch("https://example.com/dashboard", { headers: { "Cookie": cookieHeader }, }) console.log(await dashboard.text()) ``` *** ### Example 5 — Inspecting Metadata ```tsx const response = await fetch("https://example.com/video.mp4") console.log("MIME Type:", response.mimeType) console.log("Expected Length:", response.expectedContentLength) ``` *** ## Summary The `Response` class in **Scripting** offers a rich and extensible interface for handling HTTP responses: - Compatible with the standard Fetch API - Adds native **cookie parsing** and management - Supports **binary data streams** via the `Data` type - Provides full access to headers, MIME type, and encoding - Allows seamless use with `FormData` and `ReadableStream` --- url: /doc_v2/guide/Utilities/Request/fetch.md --- # 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 ```ts function fetch(url: string, init?: RequestInit): Promise function fetch(request: Request): Promise ``` *** ## 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. ```ts type RequestInit = { method?: string; headers?: HeadersInit; body?: Data | FormData | string | ArrayBuffer; allowInsecureRequest?: boolean; handleRedirect?: (newRequest: RedirectRequest) => Promise; shouldAllowRedirect?: (newRequest: Request) => Promise; // deprecated timeout?: number; // seconds signal?: AbortSignal; cancelToken?: CancelToken; // deprecated debugLabel?: string; } ``` #### Parameter Details | Property | Type | Description | | | ------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | - | | **method** | `string` | The HTTP method, such as `"GET"`, `"POST"`, `"PUT"`, `"DELETE"`. Defaults to `"GET"`. | | | **headers** | `HeadersInit` | The request headers. Can be a `Headers` object, a key-value object, or an array of `[key, value]` pairs. | | | **body** | `Data` \| `FormData` \| `string` \| `ArrayBuffer` | The request body. Only used for methods other than `GET` or `HEAD`. | | | **allowInsecureRequest** | `boolean` | Whether to allow HTTP requests when running in an HTTPS context. Defaults to `false`. | | | **handleRedirect** | `(newRequest: RedirectRequest) => Promise` | Custom redirect handler. Return `null` to cancel the redirect. | | | **shouldAllowRedirect** | `(newRequest: Request) => Promise` | Deprecated. Use `handleRedirect` instead. | | | **timeout** | `number` | Timeout duration in seconds. Throws an `AbortError` when exceeded. | | | **signal** | `AbortSignal` | A signal object from `AbortController` that can abort the request. | | | **cancelToken** | `CancelToken` | Deprecated. Use `signal` instead. | | | **debugLabel** | `string` | A label shown in the log panel for debugging and tracing requests. | | *** ## Return Value Returns a `Promise`. 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 | Error Type | Trigger Condition | | ---------------- | ---------------------------------------------------------------- | | **`TypeError`** | Invalid URL, unsupported protocol, or incompatible request body. | | **`AbortError`** | The request was aborted via `AbortController` or timed out. | *** ## Examples ### Example 1 — Basic GET Request ```tsx const response = await fetch("https://api.example.com/data") if (response.ok) { const json = await response.json() console.log(json) } else { console.log("Request failed:", response.status) } ``` *** ### Example 2 — POST Request with JSON Body ```tsx const response = await fetch("https://api.example.com/posts", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ title: "Hello", content: "World" }), }) const result = await response.json() console.log(result) ``` *** ### Example 3 — Uploading Files via `FormData` ```tsx const form = new FormData() form.append("file", Data.fromFile("/path/to/image.png"), "image/png", "image.png") form.append("user", "Tom") const response = await fetch("https://api.example.com/upload", { method: "POST", body: form, }) console.log(await response.json()) ``` *** ### Example 4 — Timeout Handling ```tsx try { const response = await fetch("https://example.com/slow", { timeout: 10 }) const text = await response.text() console.log(text) } catch (err) { if (err.name === "AbortError") { console.log("Request aborted due to timeout") } } ``` *** ### Example 5 — Aborting Requests with `AbortController` ```tsx const controller = new AbortController() setTimeout(() => { controller.abort("User cancelled the request") }, 3000) try { const response = await fetch("https://example.com/large", { signal: controller.signal }) const data = await response.text() console.log(data) } catch (err) { if (err.name === "AbortError") { console.log("Request was manually aborted") } } ``` *** ### Example 6 — Custom Redirect Handling ```tsx const response = await fetch("https://example.com/redirect", { handleRedirect: async (newRequest) => { console.log("Redirect detected:", newRequest.url) if (newRequest.url.includes("forbidden")) { return null // Cancel redirect } return newRequest // Allow redirect }, }) ``` *** ### Example 7 — Debug Label for Logging ```tsx await fetch("https://api.example.com/status", { debugLabel: "Health Check", }) // The request will be labeled "Health Check" in the log panel ``` *** ## Relationship with Other Classes | Class | Description | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | **`Request`** | Represents a network request. You can pass a `Request` object to `fetch(request)` to reuse configuration. | | **`Response`** | Represents the result of a network operation, with helper methods such as `.json()`, `.text()`, `.data()`. | | **`AbortController` / `AbortSignal`** | Provides a way to abort requests programmatically. | | **`FormData`** | Builds multipart/form-data bodies for file uploads and form submissions. | | **`Headers`** | Manages HTTP request and response headers. | | **`Data`** | Represents binary data and supports conversion to multiple formats (e.g., Base64, hex). | *** ## 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` --- url: /doc_v2/guide/Utilities/SSH/SFTP Client.md --- # SFTP Client `SFTPClient` provides access to a remote file system over an SSH connection using the SFTP protocol. It supports directory operations, file management, attribute retrieval, and path resolution. Files can be opened using `openFile()`, which returns an `SFTPFile` instance for reading and writing. Instances of this class are typically created through: ```ts const sftp = await ssh.openSFTP(); ``` *** ## Properties ### `readonly isActive: boolean` Indicates whether the SFTP connection is still active. - `true`: The connection is active - `false`: The connection is closed or invalid *** ## Methods *** ## `close(): Promise` Closes the SFTP connection. #### Returns: - A promise that resolves when the connection is successfully closed. #### Example: ```ts await sftp.close(); ``` *** ## `readDirectory(atPath: string): Promise` Reads the contents of a directory. ### Parameters: - **`atPath`**: The path of the directory to read. ### Returns: An array of directory entries: ```ts { filename: string longname: string attributes: { size?: number userId?: number groupId?: number accessTime?: Date modificationTime?: Date permissions?: number } }[] ``` ### Example: ```ts const items = await sftp.readDirectory("/var/log"); ``` *** ## `createDirectory(atPath: string): Promise` Creates a directory at the specified path. ### Parameters: - `atPath`: The path where the directory should be created. ### Returns: A promise that resolves when the directory is created. ### Example: ```ts await sftp.createDirectory("/home/user/new-folder"); ``` *** ## `removeDirectory(atPath: string): Promise` Removes a directory. The directory must be empty. ### Parameters: - `atPath`: The directory path to remove. ### Example: ```ts await sftp.removeDirectory("/home/user/empty-dir"); ``` *** ## `rename(oldPath: string, newPath: string): Promise` Renames or moves a file or directory. ### Parameters: - `oldPath`: The current path. - `newPath`: The new path. ### Example: ```ts await sftp.rename("/home/user/a.txt", "/home/user/b.txt"); ``` *** ## `getAttributes(atPath: string): Promise` Retrieves file or directory metadata. ### Returns: ```ts { size?: number userId?: number groupId?: number accessTime?: Date modificationTime?: Date permissions?: number } ``` ### Example: ```ts const attrs = await sftp.getAttributes("/etc/hosts"); ``` *** ## `openFile(filePath: string, flags: SFTPOpenFileFlags | SFTPOpenFileFlags[]): Promise` Opens a file with the specified flags and returns an `SFTPFile` instance. ### Parameters: - `filePath`: The path of the file to open. - `flags`: One or more of the following: ``` "read" | "write" | "append" | "create" | "truncate" | "forceCreate" ``` ### Returns: - A promise that resolves to an `SFTPFile` object. ### Example: ```ts const file = await sftp.openFile("/home/user/log.txt", ["read"]); const data = await file.readAll(); await file.close(); ``` *** ## `remove(atPath: string): Promise` Removes a file. ### Parameters: - `atPath`: The file path to remove. ### Example: ```ts await sftp.remove("/home/user/old.txt"); ``` *** ## `getRealPath(atPath: string): Promise` Resolves symbolic links, `~`, and relative paths to an absolute path. ### Example: ```ts const real = await sftp.getRealPath("~/documents"); ``` *** \##Usage Example ```ts const ssh = await SSHClient.connect({ host: "192.168.1.10", authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "pass"), }); const sftp = await ssh.openSFTP(); // Read a directory const list = await sftp.readDirectory("/home/user"); // Open a file and read contents const file = await sftp.openFile("/home/user/info.txt", "read"); const data = await file.readAll(); await file.close(); // Create a directory await sftp.createDirectory("/home/user/new-folder"); // Delete a file await sftp.remove("/home/user/temp.txt"); await sftp.close(); ``` --- url: /doc_v2/guide/Utilities/SSH/SFTP File.md --- # SFTP File `SFTPFile` represents an opened remote file accessed through an SFTP session. It provides low-level operations such as reading, writing, retrieving attributes, and closing the file. Instances of this class are typically obtained through: ```ts const file = await sftp.openFile(path, flags) ``` *** ## Properties *** ### `readonly isActive: boolean` Indicates whether the file handle is still open. - `true`: The file is open and can be used - `false`: The file has been closed or is no longer valid *** ## Methods *** ## `readAttributes(): Promise` Reads metadata attributes of the file. ### Returns: An object containing file attributes: ```ts { size?: number userId?: number groupId?: number accessTime?: Date modificationTime?: Date permissions?: number } ``` ### Example: ```ts const attrs = await file.readAttributes() console.log(attrs.size) ``` *** ## `read(options?: { from?: number, length?: number }): Promise` Reads data from the file with optional offset and length. ### Parameters: - `from?`: The byte offset to start reading from. Defaults to `0`. - `length?`: The number of bytes to read. Defaults to reading until the end of the file. ### Returns: - A `Promise` containing the read bytes. ### Example: ```ts const data = await file.read({ from: 100, length: 50 }) ``` *** ## `readAll(): Promise` Reads the entire contents of the file. ### Returns: - A `Promise` containing all file data. ### Example: ```ts const data = await file.readAll() ``` *** ## `write(data: Data, at?: number): Promise` Writes data to the file. ### Parameters: - `data`: The binary data to write. - `at?`: The byte offset at which to start writing. - If omitted, behavior depends on the flags used to open the file: - `"append"` will write at the end of the file. - `"write"` will write from offset 0 unless the implementation maintains a current offset. ### Returns: - A promise that resolves when the write completes. ### Example: ```ts await file.write(Data.fromRawString("Hello world")) ``` *** ## `close(): Promise` Closes the file handle. After closing, `isActive` becomes `false`, and no further reads or writes are allowed. ### Example: ```ts await file.close() ``` *** ## Usage Example ```ts // Open file in read mode const file = await sftp.openFile("/home/user/info.txt", ["read"]) // Get file attributes const attrs = await file.readAttributes() // Read the entire file const allData = await file.readAll() // Read part of the file const partialData = await file.read({ from: 50, length: 100 }) // Close the file await file.close() ``` --- url: /doc_v2/guide/Utilities/SSH/SSH Authentication Method.md --- # SSH Authentication Method Represents a method for authenticating with an SSH server. This class provides static methods for creating different types of SSH authentication strategies, including password-based, RSA key, ED25519, and ECDSA (P-256, P-384, P-521) private key authentication. This class is essential when connecting to an SSH server using the `SSHClient.connect()` method. ## Static Methods ### `static passwordBased(username: string, password: string): SSHAuthenticationMethod` Creates a password-based authentication method. #### Parameters: - `username` (string): The username to use when logging into the SSH server. - `password` (string): The password corresponding to the provided username. #### Returns: - An instance of `SSHAuthenticationMethod` configured for password-based login. #### Example: ```ts const auth = SSHAuthenticationMethod.passwordBased("user1", "mypassword") ``` *** ### `static ras(username: string, sshRsa: Data, decryptionKey?: Data): SSHAuthenticationMethod | null` Creates an RSA private key–based authentication method. #### Parameters: - `username` (string): The username for SSH login. - `sshRsa` (`Data`): The RSA private key in OpenSSH format. You can load the key using the `Data.fromString()` or similar method. - `decryptionKey` (`Data`, optional): If the private key is encrypted, provide the decryption password as a `Data` object. #### Returns: - An instance of `SSHAuthenticationMethod` configured with RSA authentication, or `null` if the key is invalid. #### Example: ```ts const rsaKey = Data.fromString(privateKeyContent)! const auth = SSHAuthenticationMethod.ras("user1", rsaKey) ``` *** ### `static ed25519(username: string, sshEd25519: Data, decryptionKey?: Data): SSHAuthenticationMethod | null` Creates an ED25519 private key–based authentication method. #### Parameters: - `username` (string): The SSH username. - `sshEd25519` (`Data`): The ED25519 private key content. - `decryptionKey` (`Data`, optional): Optional decryption key if the private key is encrypted. #### Returns: - An instance of `SSHAuthenticationMethod`, or `null` if the key is not valid. #### Example: ```ts const edKey = Data.fromString(ed25519KeyContent)! const auth = SSHAuthenticationMethod.ed25519("user1", edKey) ``` *** ### `static p256(username: string, pemRepresentation: string): SSHAuthenticationMethod | null` Creates a P-256 (ECDSA) authentication method from a PEM-formatted private key. #### Parameters: - `username` (string): The username for SSH login. - `pemRepresentation` (string): The PEM-formatted private key string for ECDSA P-256. #### Returns: - An instance of `SSHAuthenticationMethod`, or `null` if the PEM is not valid. #### Example: ```ts const auth = SSHAuthenticationMethod.p256("user1", pemKeyContent) ``` *** ### `static p384(username: string, pemRepresentation: string): SSHAuthenticationMethod | null` Creates a P-384 (ECDSA) authentication method using a PEM-formatted private key. #### Parameters: - `username` (string): The SSH username. - `pemRepresentation` (string): The PEM-formatted private key string. #### Returns: - An instance of `SSHAuthenticationMethod`, or `null` if the PEM format is invalid. *** ### `static p521(username: string, pemRepresentation: string): SSHAuthenticationMethod | null` Creates a P-521 (ECDSA) authentication method using a PEM-formatted private key. #### Parameters: - `username` (string): The SSH username. - `pemRepresentation` (string): The PEM-formatted private key string. #### Returns: - An instance of `SSHAuthenticationMethod`, or `null` if the PEM format is invalid. *** ## Usage Example ```ts // Example with password const passwordAuth = SSHAuthenticationMethod.passwordBased("root", "secret123") // Example with RSA private key const privateKey = await FileManager.readAsData("/path/to/id_rsa") const rsaAuth = SSHAuthenticationMethod.ras("root", privateKey) // Connect to server const ssh = await SSHClient.connect({ host: "192.168.0.1", authenticationMethod: rsaAuth }) ``` --- url: /doc_v2/guide/Utilities/SSH/SSH Client.md --- # SSH Client The `SSHClient` class provides an interface for connecting to a remote SSH server, executing commands, opening TTY or PTY sessions, transferring files via SFTP, and performing multi-hop SSH jumps. It supports both command-based and interactive terminal-based workflows. This class is central to establishing and managing SSH sessions in your script. *** ## Static Methods ### `SSHClient.connect(options): Promise` Establishes a connection to a remote SSH server. #### Parameters: - `options` (`object`): - `host` (`string`): The hostname or IP address of the SSH server. - `port?` (`number`): The port number to connect to. Defaults to `22`. - `authenticationMethod` (`SSHAuthenticationMethod`): The authentication method to use (e.g., password, RSA key). - `trustedHostKeys?` (`string[]`): Optional list of trusted server public keys. If provided, the client will validate the server against this list. - `reconnect?` (`"never" | "once" | "always"`): Optional strategy for reconnecting if the connection drops. Default is `"never"`. #### Returns: - A `Promise` that resolves to an `SSHClient` instance upon successful connection. #### Example: ```ts const ssh = await SSHClient.connect({ host: "192.168.0.10", authenticationMethod: SSHAuthenticationMethod.passwordBased("root", "password") }) ``` *** ## Properties ### `onDisconnect: (() => void) | null` Callback function to be invoked when the SSH connection is lost or closed. #### Example: ```ts ssh.onDisconnect = () => { console.log("Disconnected from SSH server.") } ``` *** ## Instance Methods ### `executeCommand(command: string, options?): Promise` Executes a shell command on the remote server and returns its output. #### Parameters: - `command` (`string`): The command to execute. - `options?` (`object`): - `maxResponseSize?` (`number`): Maximum number of bytes to return. - `includeStderr?` (`boolean`): If `true`, includes standard error output in the result. - `inShell?` (`boolean`): If `true`, executes the command inside a shell (e.g., `sh -c`). Default is `false`. #### Returns: - A `Promise` that resolves to the command output as a string. #### Example: ```ts const result = await ssh.executeCommand("uname -a") ``` *** ### `executeCommandStream(command, onOutput, options?): Promise` Executes a command and streams its output line-by-line. #### Parameters: - `command` (`string`): The command to run. - `onOutput` (`function`): Callback `(data: Data, isStderr: boolean) => boolean` Called for each line of output. Return `false` to stop receiving output. - `options?`: - `inShell?` (`boolean`): Whether to run the command in a shell. #### Returns: - A `Promise` that resolves when the command completes. #### Example: ```ts const output = Data.fromIntArray([]) await ssh.executeCommandStream("ping -c 4 google.com", (data, isStderr) => { output.append(data) return true }) console.log(output.toDecodedString()()) ``` *** ### `withPTY(options): Promise` Opens a PTY (pseudo-terminal) session. #### Parameters: - `options` (`object`): - `wantReply?` (`boolean`): Whether to wait for a reply from the server. Defaults to `true`. - `term?` (`string`): Terminal type (default is `"xterm"`). - `terminalCharacterWidth?` (`number`): Terminal character width. Default is `80`. - `terminalRowHeight?` (`number`): Terminal row height. Default is `24`. - `terminalPixelWidth?` (`number`): Terminal pixel width. Default is `0`. - `terminalPixelHeight?` (`number`): Terminal pixel height. Default is `0`. - `onOutput` (`function`): Callback `(data: Data, isStderr: boolean) => boolean` for receiving terminal output. - `onError?` (`function`): Optional error callback `(error: string) => void`. #### Returns: - A `Promise` that resolves to a `TTYStdinWriter` instance. #### Example: ```ts let output: Data | undefined let timerId: number | undefined const writer = await ssh.withPTY({ onOutput: (data, isStderr) => { if (output == null) { output = data } else { output.append(data) } clearTimeout(timerId) timerId = setTimeout(() => { console.log(output.toDecodedString()()) output = undefined }, 500) return true } }) await writer.write("top\n") ``` *** ### `withTTY(options): Promise` Opens a TTY session with simplified options (without explicit dimensions). #### Parameters: - `options` (`object`): - `onOutput` (`function`): Callback `(data: Data, isStderr: boolean) => boolean` for receiving terminal output. - `onError?` (`function`): Optional error callback `(error: string) => void`. #### Returns: - A `Promise` that resolves to a `TTYStdinWriter`. *** ### `openSFTP(): Promise` Opens an SFTP session for file transfer operations. #### Returns: - A `Promise` that resolves to an `SFTPClient` instance. #### Example: ```ts const sftp = await ssh.openSFTP() await sftp.writeFile("/tmp/test.txt", "Hello world") ``` *** ### `jump(options): Promise` Performs an SSH jump (proxy) to another remote host from the current SSH session. #### Parameters: - `options` (`object`): - `host` (`string`): The destination host to jump to. - `port?` (`number`): Port to connect to (default is `22`). - `authenticationMethod` (`SSHAuthenticationMethod`): Authentication method for the next host. - `trustedHostKeys?` (`string[]`): Optional list of trusted host keys. #### Returns: - A `Promise` that resolves to a new `SSHClient` representing the jump connection. #### Example: ```ts const nextHop = await ssh.jump({ host: "10.0.0.2", authenticationMethod: SSHAuthenticationMethod.passwordBased("user2", "pass2") }) ``` *** ### `close(): Promise` Closes the SSH connection and releases associated resources. > **Important:** You should call this method when the SSH client is no longer needed to avoid potential memory or socket leaks. #### Returns: - A `Promise` that resolves when the SSH connection is successfully closed. #### Example: ```ts await ssh.close() ``` *** ## Usage Example ```ts const ssh = await SSHClient.connect({ host: "192.168.1.10", authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "password") }) const output = await ssh.executeCommand("uptime") console.log("Uptime:", output) const sftp = await ssh.openSFTP() await sftp.writeFile("/tmp/hello.txt", "Hello SSH") await ssh.close() ``` --- url: /doc_v2/guide/Utilities/SSH/TTY Stdin Writer.md --- # TTY Stdin Writer Represents a writable input stream for a TTY (teletypewriter) session opened over SSH. This class allows writing text to the remote terminal’s standard input and resizing the terminal window dynamically. This class is typically returned from methods such as `SSHClient.withPTY()` and `SSHClient.withTTY()`. *** ## Methods ### `write(data: string): Promise` Writes the given string to the standard input of the TTY session. #### Parameters: - `data` (`string`): The string data to send to the remote terminal’s `stdin`. This can include control characters (e.g., `"\r"` for Enter, `"\x03"` for Ctrl+C). #### Returns: - A `Promise` that resolves when the data has been successfully written to the TTY stream. #### Example: ```ts const writer = await ssh.withTTY({ onOutput: (text) => { console.log("Output:", text) return true } }) await writer.write("ls -la\n") ``` *** ### `changeSize(options: { cols: number; rows: number; pixelWidth: number; pixelHeight: number }): Promise` Resizes the remote terminal window. This is useful for applications that rely on terminal dimensions, such as text editors or full-screen tools (e.g., `vim`, `htop`). #### Parameters: - `options` (`object`): An object describing the new terminal dimensions: - `cols` (`number`): The number of character columns in the terminal (e.g., 80). - `rows` (`number`): The number of character rows in the terminal (e.g., 24). - `pixelWidth` (`number`): The pixel width of the terminal window. Use `0` if not applicable. - `pixelHeight` (`number`): The pixel height of the terminal window. Use `0` if not applicable. #### Returns: - A `Promise` that resolves once the terminal size has been successfully updated. #### Example: ```ts await writer.changeSize({ cols: 100, rows: 30, pixelWidth: 0, pixelHeight: 0 }) ``` *** ## Usage Example ```ts const ssh = await SSHClient.connect({ host: "192.168.1.10", authenticationMethod: SSHAuthenticationMethod.passwordBased("user", "password") }) const writer = await ssh.withPTY({ term: "xterm", onOutput: (text, isStderr) => { console.log(text) return true } }) await writer.write("top\n") // Resize the terminal after 2 seconds await new Promise(resolve => setTimeout(resolve, 2000)) await writer.changeSize({ cols: 120, rows: 40, pixelWidth: 0, pixelHeight: 0 }) ``` --- url: /doc_v2/guide/Utilities/Storage.md --- # Storage The `Storage` module provides a lightweight persistent key-value storage system for scripts. It allows scripts to save and retrieve simple typed data as well as binary data (`Data`). All data is persisted asynchronously in the background. By default, all values are stored in the **private domain** of the current script, which means other scripts cannot access them. To share data across multiple scripts, set the `shared: true` option to use the **shared domain** instead. *** \##Supported Data Types The following types can be stored using the Storage API: - `string` - `number` - `boolean` - `JSON` (any JSON-serializable structure) - `Data` (using `setData` / `getData`) *** \##Storage Domains | Domain | Default | Accessible By | Use Case | | ------- | ----------------------------- | ----------------------- | --------------------------------------------------------------- | | Private | Yes | Only the current script | Script-specific settings, preferences, cached content | | Shared | No (must pass `shared: true`) | All scripts | Global settings, shared preferences, multi-script communication | *** \##API Reference ## 1. `Storage.set(key, value, options?)` ```ts function set(key: string, value: T, options?: { shared: boolean }): boolean; ``` Stores a value in persistent storage. Supports `string`, `number`, `boolean`, and JSON-serializable values. ### Parameters | Name | Type | Required | Description | | -------------- | --------- | -------- | ---------------------------------------------- | | key | `string` | Yes | The key under which the value is stored | | value | `T` | Yes | The value to store | | options.shared | `boolean` | No | Store the value in the shared domain when true | ### Returns - `boolean` — whether the operation was successful. *** ## 2. `Storage.get(key, options?)` ```ts function get(key: string, options?: { shared: boolean }): T | null; ``` Retrieves a stored value. Returns `null` if the key does not exist. ### Returns - `T | null` — the value associated with the key or `null`. *** ## 3. `Storage.setData(key, data, options?)` ```ts function setData(key: string, data: Data, options?: { shared: boolean }): void; ``` Stores a `Data` object in persistent storage. *** ## 4. `Storage.getData(key, options?)` ```ts function getData(key: string, options?: { shared: boolean }): Data | null; ``` Retrieves a stored `Data` object. Returns `null` if the key does not exist. *** ## 5. `Storage.remove(key, options?)` ```ts function remove(key: string, options?: { shared: boolean }): void; ``` Removes the entry associated with the specified key. *** ## 6. `Storage.contains(key, options?)` ```ts function contains(key: string, options?: { shared: boolean }): boolean; ``` Checks whether the storage contains the specified key. *** ## 7. `Storage.clear()` ```ts function clear(): void; ``` Removes all entries from the **private storage domain**. This does **not** affect shared storage. *** ## 8. `Storage.keys()` ```ts function keys(): string[]; ``` Returns an array of all keys stored in the current storage domain. *** \##Usage Examples ## Example 1: Store and retrieve simple values ```ts import { Storage } from "scripting"; Storage.set("username", "Thom"); const name = Storage.get("username"); console.log(name); // "Thom" ``` *** ## Example 2: Store a JSON object ```ts Storage.set("profile", { name: "Alice", age: 30, }); const profile = Storage.get<{ name: string; age: number }>("profile"); console.log(profile?.age); // 30 ``` *** ## Example 3: Store and read binary Data ```ts import { Data, Storage } from "scripting"; const bytes = Data.fromUTF8("hello"); Storage.setData("payload", bytes); const result = Storage.getData("payload"); console.log(result?.toUTF8()); // "hello" ``` *** ## Example 4: Shared domain usage ```ts Storage.set("theme", "dark", { shared: true }); const theme = Storage.get("theme", { shared: true }); console.log(theme); // "dark" ``` *** ## Example 5: Check existence and remove ```ts if (Storage.contains("token")) { Storage.remove("token"); } ``` *** ## Example 6: List all keys ```ts console.log(Storage.keys()); // ["username", "profile", ...] ``` *** \##Notes and Best Practices 1. All writes are persisted asynchronously, but the method returns immediately with a success flag. 2. `Data` cannot be stored using `Storage.set()`. Use `setData()` / `getData()` instead. 3. JSON values must be fully serializable. 4. Storage is intended for small, simple data. Avoid storing large binary blobs. 5. `Storage.clear()` only clears the private domain. --- url: /doc_v2/guide/Utilities/Thread.md --- # Thread Scripting’s UI rendering system and the vast majority of JavaScript execution run on the main thread by default. In normal usage, developers rarely need to manually switch threads. However, some system APIs or internal operations may occasionally execute on a background thread. To ensure UI updates are always safe, and to support running heavy work without blocking the main thread, Scripting provides the global `Thread` API. `Thread` is a global namespace and does not require imports. *** ## `Thread.isMainThread: boolean` Indicates whether the current JavaScript execution context is running on the main thread. Most of the time this value is `true`, but certain system callbacks or asynchronous operations may occur on background threads. When performing UI updates, this property can be used to confirm that the current thread is safe for UI operations. ```ts if (Thread.isMainThread) { console.log('On main thread') } else { console.log('On background thread') } ``` *** ## `Thread.runInMain(execute: () => void): void` Executes the given function on the main thread. Because JavaScript normally runs on the main thread, you usually do not need to call this method explicitly. It is mainly useful when: - A system API callback happens on a background thread and you need to update the UI - You want to strictly ensure that a specific piece of logic runs on the main thread This method does not return a value and does not switch back to the previous thread. It simply guarantees synchronous execution on the main thread. ```ts Thread.runInMain(() => { title.value = 'Updated on main thread' }) ``` *** ## `Thread.runInBackground(execute: () => T | Promise): Promise` Runs the provided function on a background thread and returns its result as a Promise. Once the background task completes, the result is delivered back on the thread that initiated the call (typically the main thread). This is ideal for: - CPU-intensive tasks - Large data processing - Any work that should not block the UI The function may return either a value or a Promise. ```ts const total = await Thread.runInBackground(() => { let v = 0 for (let i = 0; i < 5_000_000; i++) v += i return v }) console.log('Computed result:', total) ``` Async example: ```ts const filtered = await Thread.runInBackground(async () => { const image = await loadImage() return applyFilter(image) }) Thread.runInMain(() => { setImage(filtered) }) ``` *** ## Automatic Thread Switching in Asynchronous I/O Many **asynchronous I/O methods in Scripting already run on background threads automatically**, so developers do **not** need to manually call `runInBackground` for them. Example: ```ts const text = await FileManager.readAsString(path) ``` `readAsString` automatically performs file reading on a background thread, then returns the result back on the thread where the call was made (usually the main thread). This means asynchronous I/O will **not** block the UI, even if you call them directly in your UI logic. ### Only synchronous I/O runs on the main thread For example: ```ts const text = FileManager.readAsStringSync(path) ``` Synchronous methods **always** execute on the main thread and do **not** switch threads internally. Therefore: - Avoid using synchronous I/O on large files - Prefer asynchronous versions (e.g., `readAsString`) for better performance - Use `runInBackground` only when you must perform blocking synchronous work or heavy computation *** ## Recommendations - JavaScript runs on the main thread by default; `runInMain` is rarely needed - Asynchronous I/O methods already run on background threads automatically - Use `runInBackground` for CPU-heavy or blocking synchronous tasks - If an API callback occurs on a background thread, use `runInMain` to safely update UI - Do not manipulate UI inside `runInBackground`; switch back first --- url: /doc_v2/guide/Utilities/UIImage.md --- # UIImage The `UIImage` class represents an image object that can be loaded, encoded, converted, and displayed. It supports creating images from file paths, binary data, or Base64 strings and provides multiple format conversion methods (PNG/JPEG). `UIImage` can be displayed directly in an `Image` component or used with the `Data` class for storage, uploading, or encryption. *** ## Overview `UIImage` is the core class for handling images in the scripting environment. It is commonly used for: - Loading images from local files, binary data, Base64 strings or networl URL. - Accessing image dimensions and scale - Converting image formats (e.g., PNG, JPEG) - Generating Base64-encoded strings - Adjusting rendering and resizing modes - Flipping or tinting images - Generating thumbnails - Displaying dynamic images that switch between light and dark modes *** ## Properties ### `width: number` The width of the image in pixels. ```ts const image = UIImage.fromFile("/path/to/image.png") console.log(image?.width) ``` *** ### `height: number` The height of the image in pixels. ```ts const image = UIImage.fromFile("/path/to/image.png") console.log(image?.height) ``` *** ### `scale: number` The scale factor of the image, usually `1` or `2` for Retina displays. ```ts console.log(image?.scale) ``` *** ### `imageOrientation: string` The orientation of the image. Possible values: - `"up"` - `"down"` - `"left"` - `"right"` - `"upMirrored"` - `"downMirrored"` - `"leftMirrored"` - `"rightMirrored"` - `"unknown"` *** ### `isSymbolImage: boolean` Indicates whether the image is an SF Symbol image. ```ts const symbol = UIImage.fromSFSymbol("heart.fill") console.log(symbol?.isSymbolImage) // true ``` *** ### `renderingMode: "automatic" | "alwaysOriginal" | "alwaysTemplate" | "unknown"` The rendering mode of the image: - `automatic`: Automatically determined by the system - `alwaysOriginal`: Display the image in its original color - `alwaysTemplate`: Render the image as a template (can be tinted) *** ### `resizingMode: "tile" | "stretch" | "unknown"` The resizing mode of the image: - `"tile"`: The image is tiled to fill the area - `"stretch"`: The image is stretched to fit *** ### `capInsets: { top: number, left: number, bottom: number, right: number }` The cap insets that define the stretchable area of the image. *** ### `flipsForRightToLeftLayoutDirection: boolean` Indicates whether the image automatically flips in right-to-left (RTL) layout directions. *** ## Instance Methods ### `preparingThumbnail(size: Size): UIImage | null` Creates a thumbnail with the specified size. - **Parameters:** - `size.width`: Width of the thumbnail - `size.height`: Height of the thumbnail - **Returns:** A new `UIImage` instance, or `null` if creation fails. **Example:** ```ts const image = UIImage.fromFile("/path/to/photo.jpg") const thumb = image?.preparingThumbnail({ width: 200, height: 200 }) ``` *** ### `withBaselineOffset(offset: number): UIImage` Returns a new image with the specified baseline offset, it is useful for aligning text to the bottom of an image. ```ts const offset = image?.withBaselineOffset(10) ``` *** ### `withHorizontallyFlippedOrientation(): UIImage` Returns a new image with horizontally flipped orientation. ```ts const flipped = image?.withHorizontallyFlippedOrientation() ``` *** ### `withTintColor(color: string, renderingMode?: "automatic" | "alwaysOriginal" | "alwaysTemplate"): UIImage | null` Applies a tint color to the image using the specified rendering mode. - **Parameters:** - `color`: The tint color as a string, e.g. `"#ffcc00"` or `"rgb(255,128,0)"` - `renderingMode`: The rendering mode to use. Defaults to `"automatic"` **Example:** ```ts const symbol = UIImage.fromSFSymbol("star.fill") const tinted = symbol?.withTintColor("#ffcc00", "alwaysTemplate") ``` *** ### `withRenderingMode(renderingMode: "automatic" | "alwaysOriginal" | "alwaysTemplate"): UIImage | null` Returns a new version of the image using the specified rendering mode. ```ts const templated = image?.withRenderingMode("alwaysTemplate") ``` *** ### `resizableImage(capInsets, resizingMode?): UIImage | null` Returns a new version of the image with specified cap insets and resizing mode. - **Parameters:** - `capInsets`: `{ top, left, bottom, right }` - `resizingMode`: `"tile"` or `"stretch"` (default `"tile"`) **Example:** ```ts const resizable = image?.resizableImage( { top: 10, left: 10, bottom: 10, right: 10 }, "stretch" ) ``` *** ### `renderedInCircle(radius?: number | null, fitEntireImage?: boolean): UIImage` Returns a new version of the image rendered as a circle, with optional radius and fit behavior. - **Parameters:** - `radius` (optional): The radius of the circle in points. - If not specified: - When `fitEntireImage` is `false`, the circle uses the **shortest dimension** of the image. - When `fitEntireImage` is `true`, the circle uses the **longest dimension** of the image. - `fitEntireImage` (optional): Whether to fit the entire image inside the circle. - Default value: `true`. - If set to `false`, the image fills the circular area and may be cropped. - **Returns:** - A new `UIImage` instance representing the circular rendering. **Example 1: Create a default circular avatar** ```ts const image = UIImage.fromFile("/path/to/avatar.jpg") const circle = image?.renderedInCircle() ``` **Example 2: Specify radius and fit entire image** ```ts const image = UIImage.fromFile("/path/to/photo.png") const circle = image?.renderedInCircle(60, true) ``` **Example 3: Fill mode (may crop parts of the image)** ```ts const image = UIImage.fromFile("/path/to/icon.png") const circle = image?.renderedInCircle(50, false) ``` *** ### `renderedIn(size: { width: number, height: number }, source?: { position?: ..., size?: ... }): UIImage | null` Returns a new version of the image rendered with the specified size and optional source region. - **Parameters:** - `size`: `{ width: number, height: number }` - The size of the rendered image. - `source`: `{ position?: { x: number, y: number }, size?: { width: number, height: number } }` - The source region of the image. - **Returns:** - A new `UIImage` instance if rendering succeeds, or `null` if it fails. **Example 1: Scale entire image into a rectangle** ```ts const image = UIImage.fromFile("/path/to/photo.jpg") const rendered = image?.renderedIn({width: 200, height: 200 }) ``` **Example 2: Crop and render a specific region** ```ts const image = UIImage.fromFile("/path/to/landscape.jpg") const cropped = image?.renderedIn({ width: 150, height: 150 }, position: { x: 100, y: 50 }, size: { width: 300, height: 300 } ) ``` *** ### `applySymbolConfiguration(config: UIImageSymbolConfiguration | UIImageSymbolConfiguration[]): UIImage | null` Returns a new version of the image with the specified **symbol configuration** (`UIImageSymbolConfiguration`). This method is primarily used to customize the appearance of **SF Symbols** images, including color, weight, size, rendering mode, and palette. - **Parameters:** - `config`: The symbol configuration to apply to the image. - Can be a single `UIImageSymbolConfiguration` instance, or - An array of configurations, which will be applied sequentially (later configurations may override earlier ones). - **Returns:** - A new `UIImage` instance representing the symbol with applied configuration, or `null` if the operation fails. **Example 1: Display a symbol in multicolor** ```ts const image = UIImage.fromFile("/path/to/sf_symbol.png") const config = UIImageSymbolConfiguration.preferringMulticolor() const colored = image?.applySymbolConfiguration(config) ``` **Example 2: Apply both scale and weight configurations** ```ts const image = UIImage.fromFile("/path/to/sf_symbol.png") const config = [ UIImageSymbolConfiguration.scale("large"), UIImageSymbolConfiguration.weight("bold") ] const boldLarge = image?.applySymbolConfiguration(config) ``` **Example 3: Set hierarchical and palette colors** ```ts const image = UIImage.fromFile("/path/to/symbol.png") const config = [ UIImageSymbolConfiguration.hierarchicalColor(Color.blue()), UIImageSymbolConfiguration.paletteColors([Color.red(), Color.orange()]) ] const customized = image?.applySymbolConfiguration(config) ``` *** ## UIImageSymbolConfiguration `UIImageSymbolConfiguration` is a class used to define appearance configurations for **symbol images (SF Symbols)**. Instances created with its static methods can be passed to `applySymbolConfiguration()` to modify how the symbol is rendered. ### Available Static Methods | Method | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `preferringMonochrome()` | Prefers monochrome rendering for the symbol. | | `preferringMulticolor()` | Prefers multicolor rendering for the symbol. | | `scale(value)` | Sets the scale of the symbol. Possible values: `"default"`, `"large"`, `"medium"`, `"small"`, `"unspecified"`. | | `weight(value)` | Sets the stroke weight of the symbol. Possible values: `"ultraLight"`, `"thin"`, `"light"`, `"regular"`, `"medium"`, `"semibold"`, `"bold"`, `"heavy"`, `"black"`. | | `pointSize(value)` | Sets the point size of the symbol. | | `paletteColors(value)` | Sets a color palette (array of `Color`) for multicolor or layered symbols. | | `hierarchicalColor(value)` | Applies a hierarchical color (used for layered shading effects). | | `variableValueMode(value)` | Sets how variable-value symbols are displayed. Possible values: `"automatic"`, `"color"`, `"draw"`. | | `colorRenderingMode(value)` | Sets the color rendering mode. Possible values: `"automatic"`, `"flat"`, `"gradient"`. | | `locale(identifier)` | Sets the locale for localized symbol variants (e.g., `"en"`, `"zh-Hans"`). | *** **Example: Combine multiple symbol configurations** ```ts const config = [ UIImageSymbolConfiguration.scale("medium"), UIImageSymbolConfiguration.weight("semibold"), UIImageSymbolConfiguration.preferringMonochrome(), UIImageSymbolConfiguration.colorRenderingMode("flat") ] const image = UIImage.fromFile("/path/to/symbol.png") const result = image?.applySymbolConfiguration(config) ``` *** ### `toJPEGData(compressionQuality?: number): Data | null` Converts the image to JPEG data. - **Parameters:** - `compressionQuality`: A number between `0` and `1`, default is `1`. - **Returns:** A `Data` instance or `null`. *** ### `toPNGData(): Data | null` Converts the image to PNG data. Returns a `Data` instance or `null`. *** ### `toJPEGBase64String(compressionQuality?: number): string | null` Converts the image to a Base64-encoded JPEG string. *** ### `toPNGBase64String(): string | null` Converts the image to a Base64-encoded PNG string. *** ## Static Methods ### `UIImage.fromData(data: Data): UIImage | null` Creates an image from a `Data` instance containing PNG or JPEG data. *** ### `UIImage.fromFile(filePath: string): UIImage | null` Creates an image from a file path (supports PNG, JPG, JPEG). *** ### `UIImage.fromBase64String(base64String: string): UIImage | null` Creates an image from a Base64 string. *** ### `UIImage.fromSFSymbol(name: string): UIImage | null` Creates an image from a system SF Symbol. **Example:** ```ts const heart = UIImage.fromSFSymbol("heart.fill") ``` *** ### `UIImage.fromURL(url: string): Promise` Creates an image from a URL. **Example:** ```ts const image = await UIImage.fromURL("https://example.com/image.jpg") ``` *** ## Using UIImage in the UI `UIImage` can be displayed directly in the `` component. ### Component Definition ```ts declare const Image: FunctionComponent ``` *** ### Props Definition ```ts type UIImageProps = { image: UIImage | DynamicImageSource } ``` *** ### Dynamic Image Type ```ts type DynamicImageSource = { light: T dark: T } ``` Used for automatically switching images in light and dark mode. *** ### Example: Display a Single Image ```ts const image = UIImage.fromFile("/path/to/avatar.png") ``` *** ### Example: Light and Dark Mode ```ts const lightImage = UIImage.fromFile("/path/to/light-logo.png") const darkImage = UIImage.fromFile("/path/to/dark-logo.png") ``` *** ## Common Usage Examples ### 1. Convert Image to Base64 ```ts const image = UIImage.fromFile("/path/to/image.png") const base64 = image?.toPNGBase64String() ``` *** ### 2. Compress and Save as JPEG ```ts const image = UIImage.fromFile("/path/to/photo.jpg") const jpegData = image?.toJPEGData(0.6) if (jpegData) { // Save the data to a local file } ``` *** ### 3. Restore Image from Base64 String ```ts const base64 = "iVBORw0KGgoAAAANSUhEUgAA..." const image = UIImage.fromBase64String(base64) ``` *** ### 4. Convert PNG to JPEG and Upload ```ts const image = UIImage.fromFile("/path/to/logo.png") const jpegData = image?.toJPEGData(0.8) if (jpegData) { const response = await fetch("https://example.com/upload", { method: "POST", body: jpegData.toUint8Array() }) } ``` *** ### 5. Create and Tint an SF Symbol ```ts const symbol = UIImage.fromSFSymbol("star.fill") const colored = symbol?.withTintColor("#ffcc00", "alwaysTemplate") ``` *** ### 6. Generate a Thumbnail ```ts const image = UIImage.fromFile("/path/to/large.jpg") const thumb = image?.preparingThumbnail({ width: 120, height: 120 }) ``` *** ## Summary `UIImage` is the core class for image manipulation in the Scripting environment. It provides: - Loading from files, binary data, or Base64 strings - Support for SF Symbols - Access to dimensions, scale, orientation, and rendering information - Methods for flipping, tinting, and resizing - PNG/JPEG conversion and Base64 encoding - Thumbnail generation and customizable rendering modes - Seamless integration with the `` component - Light and dark mode image switching support --- url: /doc_v2/guide/Utilities/URLSession/BackgroundURLSession.md --- # BackgroundURLSession `BackgroundURLSession` provides APIs in the **Scripting app** for creating, resuming, and managing background download and upload tasks that continue running even when your script or app is not active. > **Availability:** Only available when your script is running in the main app (`Script.env === "index"`). *** ## Namespace: `BackgroundURLSession` ### 1) `startDownload(options): URLSessionDownloadTask` **Description:** Starts a new background download task. **Signature** ```ts function startDownload(options: { url: string destination: string headers?: Record notifyOnFinished?: { success: string failure: string } }): URLSessionDownloadTask ``` **Parameters** - `url` (`string`): The URL of the file to download. - `destination` (`string`): The local file path where the downloaded file will be saved. - `headers` (`Record`, optional): Custom HTTP headers. - `notifyOnFinished` (`{ success: string, failure: string }`, optional): Whether to show a local notification when the download finishes. **Returns** - `URLSessionDownloadTask`: A download task object (the task starts automatically). **Example** ```ts const task = BackgroundURLSession.startDownload({ url: 'https://example.com/file.zip', destination: '/var/mobile/Containers/.../Downloads/file.zip', headers: { 'User-Agent': 'Scripting/1.0' }, notifyOnFinished: { success: 'Download completed', failure: 'Download failed' } }) task.resum() task.onProgress = d => console.log('Progress:', d.progress) task.onFinishDownload = (err, info) => { if (!err) console.log('Download completed at:', info.destination) } ``` *** ### 2) `resumeDownload(options): URLSessionDownloadTask` **Description:** Resumes a previously paused or interrupted download task using resume data. **Signature** ```ts function resumeDownload(options: { resumeData: Data destination: string notifyOnFinished?: { success: string failure: string } }): URLSessionDownloadTask ``` **Parameters** - `resumeData` (`Data`): The resume data returned by `cancelByProducingResumeData()`. - `destination` (`string`): The path to save the resumed download. - `notifyOnFinished` (`{ success: string, failure: string }`, optional): Whether to show a local notification when the download finishes. **Returns** - `URLSessionDownloadTask`: A resumed download task (starts automatically). **Example** ```ts const task = BackgroundURLSession.resumeDownload({ resumeData, destination: '/.../Downloads/file.zip', notifyOnFinished: { success: 'Resumed download completed', failure: 'Resumed download failed' } }) task.resume() task.onFinishDownload = (err, info) => { if (!err) console.log('Resumed download completed:', info.destination) } ``` *** ### 3) `getDownloadTasks(): Promise` **Description:** Retrieves all active or pending background download tasks currently managed by the system. Useful when your script is restarted or relaunched — you can restore callbacks and monitor ongoing tasks. **Signature** ```ts function getDownloadTasks(): Promise ``` **Returns** - `Promise`: An array of active `URLSessionDownloadTask` objects. **Example** ```ts const tasks = await BackgroundURLSession.getDownloadTasks() for (const task of tasks) { console.log('Task ID:', task.id, 'State:', task.state) task.onComplete = err => { if (err) console.error('Download failed:', err) } } ``` *** ### 4) `startUpload(options): URLSessionUploadTask` **Description:** Starts a new background upload task. **Signature** ```ts function startUpload(options: { filePath: string toURL: string method?: string headers?: Record notifyOnFinished?: { success: string failure: string } }): URLSessionUploadTask ``` **Parameters** - `filePath` (`string`): The local file path to upload. - `toURL` (`string`): The destination server URL. - `method` (`string`, optional, default `"POST"`): The HTTP method to use. - `headers` (`Record`, optional): Custom HTTP headers. - `notifyOnFinished` (`{ success: string, failure: string }`, optional): Whether to show a local notification when the upload finishes. **Returns** - `URLSessionUploadTask`: An upload task object (the task starts automatically). **Example** ```ts const task = BackgroundURLSession.startUpload({ filePath: '/.../upload.bin', toURL: 'https://api.example.com/upload', method: 'PUT', headers: { Authorization: 'Bearer token' }, notifyOnFinished: { success: 'Upload completed', failure: 'Upload failed' } }) task.resume() task.onComplete = err => { if (!err) console.log('Upload completed') else console.error('Upload failed:', err) } ``` *** ### 5) `resumeUpload(options): URLSessionUploadTask` **Description:** Resumes a paused or failed upload task using previously saved resume data (if supported by the server). **Signature** ```ts function resumeUpload(options: { resumeData: Data notifyOnFinished?: { success: string failure: string } }): URLSessionUploadTask ``` **Parameters** - `resumeData` (`Data`): Resume data returned from a previous incomplete upload. - `notifyOnFinished` (`{ success: string, failure: string }`, optional): Whether to show a local notification when the upload finishes. **Returns** - `URLSessionUploadTask`: A new resumed upload task (starts automatically). **Example** ```ts const task = BackgroundURLSession.resumeUpload({ resumeData, notifyOnFinished: { success: 'Resumed upload completed', failure: 'Resumed upload failed' } }) task.resume() task.onComplete = err => { if (!err) console.log('Resumed upload completed successfully') } ``` *** ### 6) `getUploadTasks(): Promise` **Description:** Retrieves all active or pending background upload tasks currently managed by the system. Use this method after restarting your script to reattach callbacks to ongoing uploads. **Signature** ```ts function getUploadTasks(): Promise ``` **Returns** - `Promise`: An array of active `URLSessionUploadTask` objects. **Example** ```ts const tasks = await BackgroundURLSession.getUploadTasks() for (const task of tasks) { console.log('Task ID:', task.id, 'State:', task.state) task.onComplete = err => { if (err) console.error('Upload failed:', err) } } ``` *** ## Usage Notes and Best Practices - **Start tasks:** Tasks begin in a suspended state, so you need to call `resume()` manually. - **Pause and resume:** You can temporarily pause a task using `task.suspend()` and later call `task.resume()` to continue. - **Resume support:** Download tasks can generate resume data via `cancelByProducingResumeData()`. Upload resumability depends on server capabilities. - **Task restoration:** Even if your script is terminated, ongoing background tasks continue running. When restarted, use `getDownloadTasks()` or `getUploadTasks()` to retrieve them and reattach event handlers. - **Local notifications:** The `notifyOnFinished` option only controls whether a notification is shown when a task completes; it does not affect task lifecycle or callbacks. --- url: /doc_v2/guide/Utilities/URLSession/URLSessionDownloadTask.md --- # URLSessionDownloadTask `URLSessionDownloadTask` represents a background download task created by `BackgroundURLSession.startDownload()` or `BackgroundURLSession.resumeDownload()`. It allows scripts in the **Scripting app** to download files in the foreground or background, and the task can continue even if the script is terminated or the app is suspended. Each download task is managed by the system and provides detailed state, progress, and event callbacks. *** ## Properties ### `id: string` A unique identifier for the download task. You can use this ID to recognize or reattach to the same task when your script restarts. **Example** ```ts console.log(task.id) // Prints the unique task ID ``` *** ### `state: URLSessionTaskState` The current state of the task. Possible values: - `"running"` — The task is currently downloading. - `"suspended"` — The task is paused. - `"canceling"` — The task is being canceled. - `"completed"` — The task has finished. - `"unknown"` — The state is unknown (usually when the task has been removed by the system). **Example** ```ts if (task.state === "running") { console.log("Download in progress…") } ``` *** ### `progress: URLSessionProgress` Real-time progress information for the task. Contains the following fields: - `fractionCompleted: number` — Progress fraction between `0` and `1`. - `totalUnitCount: number` — Total number of bytes to download. - `completedUnitCount: number` — Number of bytes downloaded so far. - `isFinished: boolean` — Whether the task has completed. - `estimatedTimeRemaining: number | null` — Estimated remaining time (in seconds), or `null` if unknown. **Example** ```ts const p = task.progress console.log(`Completed ${(p.fractionCompleted * 100).toFixed(2)}%`) ``` *** ### `priority: number` The priority of the download task (range: `0.0–1.0`). Defaults to `0.5`. Higher values increase the likelihood that the system will prioritize this task. **Example** ```ts task.priority = 0.8 ``` *** ### `earliestBeginDate?: Date | null` The earliest date when the download task is allowed to begin. Useful for delaying downloads or optimizing bandwidth usage. **Example** ```ts task.earliestBeginDate = new Date(Date.now() + 10_000) // start after 10 seconds ``` *** ### `countOfBytesClientExpectsToSend: number` A best-guess upper bound on the number of bytes expected to send (for system estimation only). ### `countOfBytesClientExpectsToReceive: number` A best-guess upper bound on the number of bytes expected to receive (for system estimation only). *** ## Callbacks ### `onProgress?: (details) => void` Called periodically as the download progresses. **details** includes: - `progress: number` — Progress fraction between `0` and `1`. - `bytesWritten: number` — Bytes written since the last update. - `totalBytesWritten: number` — Total bytes downloaded so far. - `totalBytesExpectedToWrite: number` — Total expected bytes for the download. **Example** ```ts task.onProgress = details => { console.log(`Download progress: ${(details.progress * 100).toFixed(1)}%`) } ``` *** ### `onFinishDownload?: (error, details) => void` Called when the download finishes (successfully or with an error). **Parameters** - `error: Error | null` — Error object if the download failed, otherwise `null`. - `details.temporary: string` — The temporary file path used by the system. - `details.destination: string | null` — The final destination path (if successful) or `null` if the download failed. > The downloaded file is automatically moved to the specified `destination` path upon completion. **Example** ```ts task.onFinishDownload = (error, details) => { if (error) { console.error("Download failed:", error) } else { console.log("Download completed at:", details.destination) } } ``` *** ### `onComplete?: (error, resumeData) => void` Called when the task finishes completely (either successfully or unsuccessfully). **Parameters** - `error: Error | null` — Error object if the download failed, otherwise `null`. - `resumeData: Data | null` — Resume data available if the download can be resumed later. **Example** ```ts task.onComplete = (error, resumeData) => { if (error) { console.error("Download error:", error) if (resumeData) { console.log("Resume data is available for resuming the download") } } else { console.log("Download completed successfully") } } ``` *** ## Methods ### `suspend(): void` Suspends the download task. While suspended, the task produces no network activity and is not subject to timeouts. You can later call `resume()` to continue. **Example** ```ts task.suspend() console.log("Task suspended") ``` *** ### `resume(): void` Resumes a suspended task. Call this only if the task is in a `"suspended"` state. **Example** ```ts task.resume() console.log("Task resumed") ``` *** ### `cancel(): void` Cancels the download task immediately. The task enters the `"canceling"` state, and the `onComplete` callback is triggered with an error once cancellation finishes. **Example** ```ts task.cancel() console.log("Task canceled") ``` *** ### `cancelByProducingResumeData(): Promise` Cancels the download task and attempts to produce resume data. If resumable, the returned promise resolves to `Data` which can be used later with `BackgroundURLSession.resumeDownload()`. Otherwise, it resolves to `null`. **Example** ```ts const resumeData = await task.cancelByProducingResumeData() if (resumeData) { console.log("Download canceled; resume data available for later resumption") } ``` *** ## Example Usage ```ts const task = BackgroundURLSession.startDownload({ url: "https://example.com/largefile.zip", destination: "/.../Downloads/largefile.zip", notifyOnFinished: true }) task.onProgress = ({ progress }) => { console.log(`Progress: ${(progress * 100).toFixed(1)}%`) } task.onFinishDownload = (error, details) => { if (error) { console.error("Download failed:", error) } else { console.log("Download completed at:", details.destination) } } task.onComplete = async (error, resumeData) => { if (error && resumeData) { console.log("Resume data available — save it to resume later") } } ``` *** ## Notes and Best Practices - You need to call `resume()` start the download when you create a task by `BackgroundURLSession.startDownload()`. - Use `cancelByProducingResumeData()` to implement **download resumption**. - Even if the script exits or is terminated, downloads continue in the background. - After restarting the script, use `BackgroundURLSession.getDownloadTasks()` to recover existing tasks and reattach callbacks. - For long-running tasks, use `notifyOnFinished` to inform the user when a download completes. --- url: /doc_v2/guide/Utilities/URLSession/URLSessionUploadTask.md --- # URLSessionUploadTask `URLSessionUploadTask` represents a background upload task instance. It is created via `BackgroundURLSession.startUpload()` or `BackgroundURLSession.resumeUpload()` and allows file uploads to continue in the **Scripting app**, even when the app is in the background or the script is terminated. Each upload task provides real-time state, progress, and event callbacks for tracking upload activity. *** ## Properties ### `id: string` A unique identifier for the upload task. This value can be used to recognize and reattach to the same task after restarting a script. **Example** ```ts console.log(task.id) // Prints the unique task ID ``` *** ### `state: URLSessionTaskState` The current state of the upload task. Possible values: - `"running"` — The task is currently uploading - `"suspended"` — The task is paused - `"canceling"` — The task is being canceled - `"completed"` — The task has completed - `"unknown"` — The task’s state is unknown (usually if removed by the system) **Example** ```ts if (task.state === "running") { console.log("Upload in progress…") } ``` *** ### `progress: URLSessionProgress` Real-time progress information for the upload task. Contains the following fields: - `fractionCompleted: number` — Completion ratio between `0` and `1` - `totalUnitCount: number` — Total number of bytes expected to upload - `completedUnitCount: number` — Number of bytes uploaded so far - `isFinished: boolean` — Whether the task has finished - `estimatedTimeRemaining: number | null` — Estimated remaining time in seconds (may be `null`) **Example** ```ts const p = task.progress console.log(`Upload progress: ${(p.fractionCompleted * 100).toFixed(1)}%`) ``` *** ### `priority: number` The upload priority (range: `0.0–1.0`). Defaults to `0.5`. Higher values indicate a higher scheduling priority for the system. **Example** ```ts task.priority = 0.8 ``` *** ### `earliestBeginDate?: Date | null` Specifies the earliest date and time when the upload task may begin. Useful for delaying uploads until conditions like network availability or power are favorable. **Example** ```ts task.earliestBeginDate = new Date(Date.now() + 5000) // Begin after 5 seconds ``` *** ### `countOfBytesClientExpectsToSend: number` A best-guess upper bound of bytes expected to send (for system estimation only). ### `countOfBytesClientExpectsToReceive: number` A best-guess upper bound of bytes expected to receive (for system estimation only). *** ## Callbacks ### `onReceiveData?: (data: Data) => void` Triggered when response data is received from the server. The `data` parameter contains binary data from the server. **Example** ```ts task.onReceiveData = data => { console.log("Received response data:", data.length, "bytes") } ``` *** ### `onComplete?: (error: Error | null, resumeData: Data | null) => void` Triggered when the upload task finishes, whether successfully or with an error. **Parameters** - `error`: If the upload failed, contains the error object; otherwise `null`. - `resumeData`: If the upload failed and can be resumed, contains resume data (`Data`); otherwise `null`. **Example** ```ts task.onComplete = (error, resumeData) => { if (error) { console.error("Upload failed:", error) if (resumeData) { console.log("Upload is resumable — save resumeData for later recovery") } } else { console.log("Upload completed successfully!") } } ``` *** ## Methods ### `suspend(): void` Pauses the upload task. A suspended task produces no network traffic and isn’t subject to timeouts. Use `resume()` to continue the upload later. **Example** ```ts task.suspend() console.log("Task suspended") ``` *** ### `resume(): void` Resumes a suspended upload task. Newly-initialized tasks begin in a suspended state, so you need to call this method to start the task. **Example** ```ts task.resume() console.log("Upload resumed") ``` *** ### `cancel(): void` Cancels the upload task immediately. The task enters the `"canceling"` state, and the `onComplete` callback is invoked with an error once cancellation finishes. **Example** ```ts task.cancel() console.log("Task canceled") ``` *** ## Example Usage ```ts const task = BackgroundURLSession.startUpload({ filePath: "/path/to/file.txt", toURL: "https://api.example.com/upload", method: "POST", headers: { Authorization: "Bearer my_token" }, notifyOnFinished: true }) task.resume() task.onReceiveData = data => { console.log("Received response:", data.length, "bytes") } task.onComplete = (error, resumeData) => { if (error) { console.error("Upload error:", error) if (resumeData) console.log("Resume data available — can retry later") } else { console.log("Upload completed successfully") } } ``` *** ## Notes and Best Practices - You can pause a task with `suspend()` and later resume it with `resume()`. - Some servers support resumable uploads; if supported, you can use `resumeData` for recovery. - Uploads can continue even if the script or app is suspended or terminated. - Use `BackgroundURLSession.getUploadTasks()` to retrieve and reattach callbacks to ongoing uploads after restarting your script. - Setting `notifyOnFinished` allows a local notification to alert users when the upload completes. - When including authorization information (e.g., `Authorization` headers), ensure credentials are stored and managed securely. --- url: /doc_v2/guide/Utilities/UUID.md --- # UUID The `UUID` module provides an easy way to generate unique UUID strings. *** ## Functions ### `string(): string` Generates a new UUID (Universally Unique Identifier) in string format. - **Returns**:\ A UUID string (e.g., `"550e8400-e29b-41d4-a716-446655440000"`). *** ## Usage Example ```tsx const id = UUID.string() console.log('Generated UUID:', id) ``` --- url: /doc_v2/guide/Utilities/WebScoket.md --- # WebScoket The `WebSocket` class provides an interface for creating and managing WebSocket connections, allowing for real-time communication with a server. You can send and receive both text and binary data, including byte buffers, over the WebSocket connection. *** ## Overview WebSocket is a communication protocol that allows full-duplex communication between a client and a server. This makes it ideal for real-time applications like live messaging, notifications, or streaming data. *** ## Class: `WebSocket` ### Constructor #### `new WebSocket(url: string)` Creates a new WebSocket connection to the specified URL and attempts to establish a connection immediately. - **Parameters**: - `url: string`: The WebSocket server URL to connect to. Example: `"ws://example.com/socket"` or `"wss://example.com/socket"` for secure WebSocket connections. - **Returns**: A `WebSocket` object representing the connection. *** ### Properties - **`url: string`**\ The URL to which the WebSocket is connected. This property is read-only. - **`onopen?: () => void`**\ Optional callback function triggered when the WebSocket connection is successfully established. - **`onerror?: (error: Error) => void`**\ Optional callback function triggered when an error occurs during the WebSocket connection or communication. - **`onmessage?: (message: string | Data) => void`**\ Optional callback function triggered when a message is received from the WebSocket server. The `message` parameter can be either a string or binary data, represented by the `Data` class. - **`onclose?: (reason?: string) => void`**\ Optional callback function triggered when the WebSocket connection is closed. The `reason` parameter provides an optional explanation for the closure. *** ### Methods #### `send(message: string | Data): void` Sends data to the server over the WebSocket connection. - **Parameters**: - `message: string | Data`: The data to be sent to the server. It can be a string or an instance of the `Data` class. - **Returns**: `void` #### `close(code?: 1000 | 1001 | 1002 | 1003, reason?: string): void` Closes the WebSocket connection. If the connection is already closed, this method does nothing. - **Parameters**: - `code?: 1000 | 1001 | 1002 | 1003`: An optional WebSocket connection close code. Common codes include: - `1000`: Normal closure - `1001`: Going away - `1002`: Protocol error - `1003`: Unsupported data type - `reason?: string`: An optional reason for closing the connection. This string must be no longer than 123 bytes (UTF-8 encoded). - **Returns**: `void` *** ### Event Handling You can listen for WebSocket events using `addEventListener` and remove event listeners with `removeEventListener`. #### `addEventListener(event: "open", listener: () => void): void` Adds an event listener for the `"open"` event, triggered when the WebSocket connection is established. #### `addEventListener(event: "error", listener: (error: Error) => void): void` Adds an event listener for the `"error"` event, triggered when an error occurs during the WebSocket connection. #### `addEventListener(event: "message", listener: (message: string | Data) => void): void` Adds an event listener for the `"message"` event, triggered when a message is received from the WebSocket server. #### `addEventListener(event: "close", listener: (reason?: string) => void): void` Adds an event listener for the `"close"` event, triggered when the WebSocket connection is closed. #### `removeEventListener(event: "open", listener: () => void): void` Removes an event listener for the `"open"` event. #### `removeEventListener(event: "error", listener: (error: Error) => void): void` Removes an event listener for the `"error"` event. #### `removeEventListener(event: "message", listener: (message: string | Data) => void): void` Removes an event listener for the `"message"` event. #### `removeEventListener(event: "close", listener: (reason?: string) => void): void` Removes an event listener for the `"close"` event. *** ## Example Usage ### Establishing a WebSocket Connection ```ts const ws = new WebSocket("wss://example.com/socket") // Set up event listeners ws.addEventListener("open", () => { console.log("Connection established!") ws.send("Hello, Server!") }) ws.addEventListener("message", (message) => { console.log("Received message:", message) }) ws.addEventListener("error", (error) => { console.log("WebSocket error:", error) }) ws.addEventListener("close", (reason) => { console.log("Connection closed:", reason) }) ``` ### Sending a String Message ```ts const ws = new WebSocket("wss://example.com/socket") ws.addEventListener("open", () => { ws.send("Hello, this is a test message!") }) ``` ### Sending Binary Data Using `Data` ```ts const ws = new WebSocket("wss://example.com/socket") ws.addEventListener("open", () => { const data = Data.fromString("some message") ws.send(data) // Send binary data }) ``` ### Handling Binary Data ```ts const ws = new WebSocket("wss://example.com/socket") ws.addEventListener("message", (message) => { if (message instanceof Data) { const byteArray = message.getBytes() if (byteArray) { console.log("Received binary data:", byteArray) } } }) ``` ### Closing the WebSocket Connection ```ts const ws = new WebSocket("wss://example.com/socket") ws.addEventListener("open", () => { console.log("Connection established!") // Close the connection with a custom reason ws.close(1000, "Closing connection after test") }) ``` *** ## Notes - The `send()` method can handle both text and binary data. For binary data, you can use the `Data` class to handle the byte buffer. - For binary data, ensure that your WebSocket server is capable of handling binary data, such as `ArrayBuffer` or `Uint8Array`. - The `close()` method can take a `code` and an optional `reason` to specify how the WebSocket connection should close. --- url: /doc_v2/guide/Utilities/socket.io.md --- # socket.io The `Socket.IO` API provides robust tools for managing real-time, bidirectional communication between clients and servers. It includes a `SocketManager` for handling multiple namespaces and a `SocketIOClient` for individual socket connections. This document provides an overview of the API, including setup, configuration, and usage. *** ## Getting Started The `Socket.IO` API allows you to create and manage WebSocket connections using a `SocketManager`. Each `SocketManager` can handle multiple namespaces and configurations. ### Example: ```typescript // Create a SocketManager instance const manager = new SocketManager("http://localhost:8080", { reconnects: true, reconnectAttempts: 5, compress: true }) // Access the default namespace socket const defaultSocket = manager.defaultSocket // Create a socket for a specific namespace const roomASocket = manager.socket("/roomA") ``` *** ## API Reference ### SocketManager #### Constructor **`constructor(url: string, config?: SocketManagerConfig)`** - **`url`**: The URL of the Socket.IO server. - **`config`**: Optional configuration object. #### Properties - **`socketURL: string`**: The server URL. - **`status: SocketIOStatus`**: The manager's connection status (`connected`, `connecting`, `disconnected`, etc.). - **`defaultSocket: SocketIOClient`**: The socket for the default namespace (`"/"`). #### Methods - **`socket(namespace: string): SocketIOClient`** - Returns a `SocketIOClient` for the specified namespace. - **`setConfigs(config: SocketManagerConfig): void`** - Updates the manager's configuration. - **`disconnect(): void`** - Disconnects all sockets managed by this instance. - **`reconnect(): void`** - Attempts to reconnect to the server. ### SocketIOClient #### Properties - **`id: string | null`**: The unique identifier for the socket connection. - **`status: SocketIOStatus`**: The client's connection status (`connected`, `connecting`, etc.). #### Methods - **`connect(): void`** - Initiates a connection. - **`disconnect(): void`** - Disconnects the socket. - **`emit(event: string, data: any): void`** - Sends an event to the server with associated data. - **`on(event: string, callback: (data: any[], ack: (value?: any) => void) => void): void`** - Registers an event listener. *** ## Configuration The `SocketManagerConfig` object allows you to customize connection behavior. ### Key Options: - **`compress`**: Enables compression for WebSocket transport. - **`connectParams`**: A dictionary of GET parameters included in the connection URL. - **`cookies`**: An array of cookies to send during the initial connection. - **`forceNew`**: Ensures a new engine is created for every connection. - **`reconnects`**: Enables automatic reconnection. - **`reconnectAttempts`**: Sets the maximum number of reconnection attempts. - **`reconnectWait`**: Minimum time (in seconds) between reconnection attempts. ### Example: ```typescript const config: SocketManagerConfig = { compress: true, reconnects: true, reconnectAttempts: 5, reconnectWait: 2, extraHeaders: { Authorization: "Bearer token" } } const manager = new SocketManager("http://example.com", config) ``` *** ## Common Use Cases ### Emit and Listen to Events ```typescript const socket = manager.defaultSocket socket.on("connect", () => { console.log("Connected to server") socket.emit("joinRoom", { room: "roomA" }) }) socket.on("message", (data) => { console.log("Message received:", data) }) ``` ### Handle Reconnection ```typescript manager.setConfigs({ reconnects: true, reconnectAttempts: 10 }) manager.defaultSocket.on("reconnect", () => { console.log("Reconnected to server") }) ``` ### Use Namespaces ```typescript const chatSocket = manager.socket("/chat") chatSocket.on("newMessage", (data) => { console.log("New message in chat:", data) }) ``` *** ## Best Practices 1. **Manage Lifecycles:** Always call `disconnect()` when sockets are no longer needed. 2. **Namespace Isolation:** Use separate namespaces for logically distinct communication channels. 3. **Reconnection Strategies:** Configure reconnection parameters based on your app's requirements. 4. **Error Handling:** Register an `on("error")` handler to gracefully handle connection issues. 5. **Secure Connections:** Use secure WebSocket (WSS) for sensitive data and configure `secure: true`. *** ## Full Example ```typescript // Create a SocketManager with configuration const manager = new SocketManager("https://example.com", { reconnects: true, reconnectAttempts: -1, reconnectWait: 1 }) // Access the default namespace const socket = manager.defaultSocket // Register event handlers socket.on("connect", () => { console.log("Connected to server") socket.emit("join", { room: "lobby" }) }) socket.on("message", (data) => { console.log("Message received:", data) }) socket.on("disconnect", () => { console.log("Disconnected from server") }) // Emit a custom event socket.emit("sendMessage", { text: "Hello, world!" }) // Disconnect when done setTimeout(() => { manager.disconnect() }, 60000) ``` --- url: /doc_v2/guide/View Modifiers/Animation and Transition.md --- # Animation and Transition Scripting Animation & Transition System ## Animation Class The `Animation` class describes how values animate in time. ## Factory Methods ### `Animation.default()` Creates a default system animation. ```ts static default(): Animation ``` *** ### `Animation.linear(duration?)` ```ts static linear(duration?: number | null): Animation ``` Constant-speed animation. *** ### `Animation.easeIn(duration?)` ```ts static easeIn(duration?: number | null): Animation ``` *** ### `Animation.easeOut(duration?)` ```ts static easeOut(duration?: number | null): Animation ``` *** ### `Animation.bouncy(options?)` ```ts static bouncy(options?: { duration?: number extraBounce?: number }): Animation ``` Spring-like animation with additional bounce. *** ### `Animation.smooth(options?)` ```ts static smooth(options?: { duration?: number extraBounce?: number }): Animation ``` *** ### `Animation.snappy(options?)` ```ts static snappy(options?: { duration?: number extraBounce?: number }): Animation ``` *** ### `Animation.spring(options?)` Supports two mutually exclusive modes. ```ts static spring(options?: { blendDuration?: number } & ( | { duration?: number bounce?: number response?: never dampingFraction?: never } | { response?: number dampingFraction?: number duration?: never bounce?: never } )): Animation ``` *** ### `Animation.interactiveSpring(options?)` ```ts static interactiveSpring(options?: { response?: number dampingFraction?: number blendDuration?: number }): Animation ``` *** ### `Animation.interpolatingSpring(options?)` ```ts static interpolatingSpring(options?: { mass?: number stiffness: number damping: number initialVelocity?: number } | { duration?: number bounce?: number initialVelocity?: number mass?: never stiffness?: never damping?: never }): Animation ``` *** ## Modifier Methods ### `.delay(time)` ```ts delay(time: number): Animation ``` ### `.repeatCount(count, autoreverses)` ```ts repeatCount(count: number, autoreverses?: boolean): Animation ``` ### `.repeatForever(autoreverses)` ```ts repeatForever(autoreverses?: boolean): Animation ``` *** ## Transition Class `Transition` describes how a view enters or leaves the hierarchy. ## Instance Methods ### `.animation(animation)` Attach a specific animation to a transition. ```ts animation(animation?: Animation): Transition ``` ### `.combined(other)` Combine transitions. ```ts combined(other: Transition): Transition ``` *** ## Static Transitions ### Identity ```ts Transition.identity(); ``` ### Move ```ts Transition.move(edge: Edge) ``` ### Offset ```ts Transition.offset(position?: Point) ``` ### Push ```ts Transition.pushFrom(edge: Edge) ``` ### Opacity ```ts Transition.opacity(); ``` ### Scale ```ts Transition.scale(scale?: number, anchor?: Point | KeywordPoint) ``` ### Slide ```ts Transition.slide(); ``` ### Fade ```ts Transition.fade(duration?: number) ``` ### Flip transitions ```ts Transition.flipFromLeft(duration?) Transition.flipFromRight(duration?) Transition.flipFromTop(duration?) Transition.flipFromBottom(duration?) ``` ### Asymmetric ```ts Transition.asymmetric(insertion: Transition, removal: Transition) ``` *** ## withAnimation ```ts function withAnimation(body: () => void): Promise; function withAnimation(animation: Animation, body: () => void): Promise; function withAnimation( animation: Animation, completionCriteria: "logicallyComplete" | "removed", body: () => void, ): Promise; ``` Wraps a state update and animates any affected values. Example: ```ts withAnimation(Animation.easeOut(0.3), () => { visible.setValue(false); }); ``` *** ## Correct Usage of the animation View Modifier ### (Important Correction) In Scripting, the `animation` prop is **not**: ```tsx animation = { anim }; // incorrect ``` The correct format is: ```tsx animation={{ animation: anim, value: }} ``` ### Meaning: | Field | Description | | ----------- | ----------------------------------------------------- | | `animation` | The `Animation` instance to use | | `value` | The observable value whose changes should be animated | This mirrors SwiftUI’s `.animation(animation, value: value)` modifier. *** ## Correct Examples ### Example: Animate size changes ```tsx const size = useObservable(100) const anim = Animation.spring({ duration: 0.3, bounce: 0.3 })

`) - Or directly on the `` component itself *** ## `listItemTint` Sets the **tint color** applied to the row or its accessories (e.g., icons, buttons). ### Type ```ts listItemTint?: Color ``` ### Description - Use this to override the inherited tint color for a row or its content. - Use `null` to avoid overriding the inherited tint. ### Example ```tsx Tinted Row ``` *** ## `listRowInsets` Applies **padding (insets)** to a row in a list. ### Type ```ts listRowInsets?: number | EdgeInsets ``` ### Description - Use a single `number` to apply uniform padding. - Use an `EdgeInsets` object to apply individual insets for top, bottom, leading, and trailing. ### Example ```tsx Custom Insets Row ``` *** ## `listRowSpacing` Controls the **vertical spacing** between adjacent rows. ### Type ```ts listRowSpacing?: number ``` ### Example ```tsx Row 1 Row 2 ``` *** ## `listRowSeparator` Sets the **visibility of the separator line** for a specific row. ### Type ```ts listRowSeparator?: Visibility | { visibility: Visibility edges: VerticalEdgeSet } ``` ### `Visibility` options: - `"visible"` – Always show the separator - `"hidden"` – Hide the separator - `"automatic"` – System default behavior ### `VerticalEdgeSet` options: - `"top"` | `"bottom"` | `"all"` ### Example ```tsx No Bottom Separator ``` *** ## `listRowSeparatorTint` Sets the **tint color of the separator** for a specific row. ### Type ```ts listRowSeparatorTint?: Color | { color: Color edges: VerticalEdgeSet } ``` ### Example ```tsx Colored Separator ``` *** ## `listRowBackground` Places a **custom background** behind a list row. ### Type ```ts listRowBackground?: VirtualNode ``` ### Example ```tsx } > Row with background ``` *** ## `listSectionSpacing` Controls the **spacing between adjacent list sections**. ### Type ```ts listSectionSpacing?: ListSectionSpacing ``` ### `ListSectionSpacing` options: - `"default"` – System default spacing - `"compact"` – Smaller spacing - A `number` – Custom spacing in points ### Example ```tsx

...

``` *** ## `listSectionSeparator` Controls the **visibility of the separator** between list sections. ### Type ```ts listSectionSeparator?: Visibility | { visibility: Visibility edges: VerticalEdgeSet } ``` ### Example ```tsx

Section Content

``` *** ## `listSectionSeparatorTint` Sets the **separator tint color** for a section. ### Type ```ts listSectionSeparatorTint?: Color | { color: Color edges: VerticalEdgeSet } ``` ### Example ```tsx

Styled Section

``` *** ## Supporting Types ## `EdgeInsets` ```ts { top: number bottom: number leading: number trailing: number } ``` ## `Visibility` ```ts "automatic" | "visible" | "hidden" ``` ## `VerticalEdgeSet` ```ts "top" | "bottom" | "all" ``` ## `Color` formats You can define color in three ways: - Named keyword: `"green"`, `"label"`, etc. - Hex: `"#ff0000"` - RGBA: `"rgba(255,0,0,1)"` *** ## Summary Table | Modifier | Scope | Description | | -------------------------- | ------- | --------------------------------- | | `listItemTint` | Row | Sets tint color for row content | | `listRowInsets` | Row | Custom padding for row | | `listRowSpacing` | List | Vertical spacing between rows | | `listRowSeparator` | Row | Controls row separator visibility | | `listRowSeparatorTint` | Row | Tint color of row separator | | `listRowBackground` | Row | Background behind a specific row | | `listSectionSpacing` | List | Spacing between sections | | `listSectionSeparator` | Section | Visibility of section separator | | `listSectionSeparatorTint` | Section | Tint color of section separator | --- url: /doc_v2/guide/View Modifiers/List and Section View Modifiers/New List View Modifiers.md --- # New List View Modifiers \##Overview of Properties | Property | Type | Availability | Description | | | | ---------------------------- | ----------------------------------------------------------- | ------------ | ------------------------------------------------------------------ | - | - | | `listSectionIndexVisibility` | `Visibility` | iOS 26.0+ | Controls the visibility of the List's right-side section index | | | | `listSectionMargins` | `number \| EdgeSets \| { edges: EdgeSets; length: number }` | iOS 26.0+ | Customizes section margins, replacing SwiftUI’s automatic defaults | | | | `sectionIndexLabel` | `string` | iOS 26.0+ | Sets the character displayed in the section index | | | | `sectionActions` | `VirtualNode` | iOS 18.0+ | Adds custom actions to the section header area | | | *** \##1. listSectionIndexVisibility ```ts /** * Sets the visibility of the list section index. * @available iOS 26.0+. */ listSectionIndexVisibility?: Visibility ``` ### Description Controls whether the List shows the right-side section index (commonly used for A–Z navigation in contact lists). Possible values: - `"visible"` - `"hidden"` - `"automatic"` (default system behavior) ### Example ```tsx (

{group.title}} sectionIndexLabel={group.title}> {group.items.map((item) => ( {item} ))}

)} /> ``` *** \##2. listSectionMargins ```ts /** * Set the section margins for the specific edges. * @available iOS 26.0+. */ listSectionMargins?: number | EdgeSets | { edges: EdgeSets length: number } ``` ### Description Customizes the margins of a section. When set, it **fully replaces** SwiftUI’s default section margin rules. ### Supported Formats ### 2.1 Single number Applies the same margin to all edges. ```tsx listSectionMargins={12} ``` ### 2.2 EdgeSets Applies the specified edges with the default margin. ```tsx listSectionMargins={["horizontal", "top"]} ``` ### 2.3 Specific edges with length Applies a margin of `length` only to the specified edges. ```tsx listSectionMargins={{ edges: "horizontal", length: 20 }} ``` Equivalent to SwiftUI: ```swift .listSectionMargins(.horizontal, 20) ``` ### Example ```tsx

Favorites} listSectionMargins={{ edges: "horizontal", length: 20, }}> Item A Item B

``` *** \##3. sectionIndexLabel ```ts /** * Sets the label that is used in a section index. * @available iOS 26.0+. */ sectionIndexLabel?: string ``` ### Description Sets the character or text displayed in the right-side section index for this section. Typically a single letter. ### Example ```tsx

A} sectionIndexLabel="A"> Adam Ana

``` *** \##4. sectionActions ```ts /** * Adds custom actions to a section. * @available iOS 18.0+ */ sectionActions?: VirtualNode ``` ### Description Adds custom UI elements such as buttons or menus to the section header’s trailing (accessory) area. ### Example: Refresh button ```tsx

Downloads} sectionActions={

Custom WebView

Custom WebView

Welcome

Welcome to Scripting Server

Inline HTML Body

Welcome