# node:path

O módulo `node:path` fornece os utilitários do Node.js para trabalhar com caminhos de arquivos e diretórios. Suas funções unem, dividem, normalizam e analisam caminhos, e uma function as usa para construir caminhos quando roteia requisições ou compõe referências a assets. O Azion Runtime não dá a uma function acesso a um sistema de arquivos real, então toda função de `path` opera apenas em strings de caminho. Por exemplo, `path.resolve()` retorna uma string sem ler um diretório.

---

## Exemplos

As functions abaixo são executadas de forma independente: cada uma importa `path` de `node:path`, e cada saída é a que uma function com deploy feito retorna.

### Operações básicas com path

Esta function une três segmentos em um caminho, registra o caminho no log e o retorna no corpo da resposta:

```javascript
/**
 * An example of using the Node.js Path API in an Azion Function.
 * Support:
 * - Partially supported (Extended by library `path-browserify`)
 * @module runtime-apis/nodejs/path/main
 * @example
 * // Build and run with the Azion CLI:
 * azion build
 * azion dev
 */
import path from "node:path";

/**
 * An example of using the Node.js Path API in an Azion Function.
 * @param {*} event
 * @returns {Promise<Response>}
 */
const main = async (event) => {
  const pathName = path.join("/", "images", "image.jpg");
  console.log("Path", pathName);
  return new Response(`Path: ${pathName}`);
};

export default main;
```

A function registra `Path /images/image.jpg` no log e responde com este corpo:

```text
Path: /images/image.jpg
```

### Roteamento de URL com path

Esta function divide o caminho da requisição em diretório, nome do arquivo e extensão. Depois, constrói um caminho de API e um caminho absoluto a partir dessas partes:

```javascript
import path from "node:path";

const main = async (event) => {
  const requestUrl = new URL(event.request.url);
  const pathname = requestUrl.pathname;

  // Extract path components
  const dirname = path.dirname(pathname);
  const basename = path.basename(pathname);
  const extname = path.extname(pathname);

  console.log("Directory:", dirname);
  console.log("Filename:", basename);
  console.log("Extension:", extname);

  // Build a new path for routing
  const apiPath = path.join("/api", "v1", "users", basename);
  console.log("API path:", apiPath);

  // In Azion Runtime, path.resolve() manipulates path strings only;
  // it does not read a filesystem
  const absolutePath = path.resolve("/app", "public", "images", "logo.png");
  console.log("Absolute path:", absolutePath);

  return new Response(JSON.stringify({
    original: pathname,
    dirname,
    basename,
    extname,
    apiPath,
    absolutePath
  }), {
    headers: { "Content-Type": "application/json" }
  });
};

export default main;
```

Para uma requisição a `/docs/getting-started`, um caminho sem extensão de arquivo, a function responde com cada parte do caminho e os dois caminhos que construiu:

```json
{"original":"/docs/getting-started","dirname":"/docs","basename":"getting-started","extname":"","apiPath":"/api/v1/users/getting-started","absolutePath":"/app/public/images/logo.png"}
```

### Normalização e análise de caminhos

Esta function normaliza um caminho que contém `..`, `.` e uma barra dupla. Depois, analisa um caminho em suas partes, constrói um caminho a partir de um objeto e verifica se dois caminhos são absolutos:

```javascript
import path from "node:path";

const main = async (event) => {
  // Normalize messy paths
  const messyPath = "/users/../public/./images//photo.jpg";
  const normalizedPath = path.normalize(messyPath);
  console.log("Normalized:", normalizedPath);
  // /public/images/photo.jpg

  // Parse path into components
  const filePath = "/assets/css/styles.css";
  const parsed = path.parse(filePath);
  console.log("Parsed:", parsed);
  // { root: '/', dir: '/assets/css', base: 'styles.css', ext: '.css', name: 'styles' }

  // Format path from object
  const formatted = path.format({
    root: "/",
    dir: "/data/documents",
    base: "report.pdf"
  });
  console.log("Formatted:", formatted);

  // Check if path is absolute
  const isAbs1 = path.isAbsolute("/assets/app.js");
  const isAbs2 = path.isAbsolute("../relative/path");
  console.log("Is absolute:", isAbs1, isAbs2);

  return new Response(JSON.stringify({
    normalizedPath,
    parsed,
    formatted,
    isAbsolute: { absolute: isAbs1, relative: isAbs2 }
  }), {
    headers: { "Content-Type": "application/json" }
  });
};

export default main;
```

A function responde com o caminho normalizado, as partes analisadas, o caminho formatado e as duas verificações:

```json
{"normalizedPath":"/public/images/photo.jpg","parsed":{"root":"/","dir":"/assets/css","base":"styles.css","ext":".css","name":"styles"},"formatted":"/data/documents/report.pdf","isAbsolute":{"absolute":true,"relative":false}}
```

### Separadores de caminho e variantes de plataforma

Esta function une os mesmos segmentos com as variantes padrão, POSIX e Windows do módulo e lê cada separador e o delimitador:

```javascript
import path from "node:path";

const main = async (event) => {
  // Default path methods (POSIX rules in Azion Runtime)
  const defaultJoin = path.join("folder", "subfolder", "file.txt");
  const defaultSep = path.sep;

  // POSIX-style paths (forward slashes)
  // path.posix and path.win32 are properties of the main module
  const posixJoin = path.posix.join("folder", "subfolder", "file.txt");
  const posixSep = path.posix.sep;

  // Windows-style methods: in Azion Runtime, they also use forward slashes
  const win32Join = path.win32.join("folder", "subfolder", "file.txt");
  const win32Sep = path.win32.sep;

  console.log("Default join:", defaultJoin);
  console.log("POSIX join:", posixJoin);
  console.log("Windows join:", win32Join);

  // Get delimiter for PATH environment variable
  const delimiter = path.delimiter;
  console.log("Path delimiter:", delimiter);

  return new Response(JSON.stringify({
    default: { join: defaultJoin, sep: defaultSep },
    posix: { join: posixJoin, sep: posixSep },
    win32: { join: win32Join, sep: win32Sep },
    delimiter
  }), {
    headers: { "Content-Type": "application/json" }
  });
};

export default main;
```

A function responde com o mesmo caminho unido e o separador `/` nas três variantes, e com `:` como delimitador:

```json
{"default":{"join":"folder/subfolder/file.txt","sep":"/"},"posix":{"join":"folder/subfolder/file.txt","sep":"/"},"win32":{"join":"folder/subfolder/file.txt","sep":"/"},"delimiter":":"}
```

---

## APIs suportadas

A tabela lista o status de cada API de `node:path` no Azion Runtime:

| API                 | Status             |
| ------------------- | ------------------ |
| `path.basename()`   | 🟢 Com suporte     |
| `path.dirname()`    | 🟢 Com suporte     |
| `path.extname()`    | 🟢 Com suporte     |
| `path.format()`     | 🟢 Com suporte     |
| `path.isAbsolute()` | 🟢 Com suporte     |
| `path.join()`       | 🟢 Com suporte     |
| `path.normalize()`  | 🟢 Com suporte     |
| `path.parse()`      | 🟢 Com suporte     |
| `path.relative()`   | 🟢 Com suporte     |
| `path.resolve()`    | 🟢 Com suporte     |
| `path.sep`          | 🟢 Com suporte     |
| `path.delimiter`    | 🟢 Com suporte     |
| `path.posix`        | 🟢 Com suporte     |
| `path.win32`        | 🟡 Suporte parcial |

`path.win32.join()` une segmentos com `/`, então `path.win32.join("C:\\a", "b")` retorna `C:/a/b`, e `path.win32.sep` é `/`.

Toda função de `path` opera em strings de caminho, sem acesso ao sistema de arquivos. `path.resolve()` resolve segmentos relativos a partir de `/`, então `path.resolve("a", "b")` retorna `/a/b`. Para trabalhar com o caminho de uma requisição, leia-o com a API Web `URL`, como em `new URL(event.request.url).pathname`, e passe-o para as funções de `node:path`.

---

## Recursos relacionados

- [APIs do Node.js](/pt-br/documentacao/devtools/runtime/node.md): O status de cada módulo do Node.js no Azion Runtime, incluindo `path`.
- [Use APIs do Node.js com polyfills](/pt-br/documentacao/guias/desenvolvimento-de-aplicacoes/functions-e-runtime/use-polyfills.md): Como o build transforma imports `node:` em código que é executado no Azion Runtime.
- [node:url](/pt-br/documentacao/devtools/runtime/node/url.md): O módulo do Node.js que analisa e formata as URLs cujos caminhos `node:path` manipula.
- [Documentação de path do Node.js](https://nodejs.org/api/path.html): A referência completa do Node.js para cada API de `node:path` da tabela.