Path

[Estável: 2 - Estável]

Código Fonte: lib/path.js

O módulo node:path fornece utilitários para trabalhar com caminhos de arquivos e diretórios. Ele pode ser acessado usando:

CJSESM

const path = require('node:path');

import path from 'node:path';

Windows vs. POSIX

A operação padrão do módulo node:path varia de acordo com o sistema operacional no qual um aplicativo Node.js está sendo executado. Especificamente, ao ser executado em um sistema operacional Windows, o módulo node:path assume que caminhos no estilo Windows estão sendo usados.

Portanto, usar path.basename() pode produzir resultados diferentes no POSIX e no Windows:

No POSIX:

path.basename('C:\\temp\\myfile.html');
// Retorna: 'C:\\temp\\myfile.html'

No Windows:

path.basename('C:\\temp\\myfile.html');
// Retorna: 'myfile.html'

Para obter resultados consistentes ao trabalhar com caminhos de arquivos do Windows em qualquer sistema operacional, use path.win32:

No POSIX e no Windows:

path.win32.basename('C:\\temp\\myfile.html');
// Retorna: 'myfile.html'

Para obter resultados consistentes ao trabalhar com caminhos de arquivos POSIX em qualquer sistema operacional, use path.posix:

No POSIX e no Windows:

path.posix.basename('/tmp/myfile.html');
// Retorna: 'myfile.html'

No Windows, o Node.js segue o conceito de diretório de trabalho por unidade. Esse comportamento pode ser observado ao usar um caminho de unidade sem uma barra invertida. Por exemplo, path.resolve('C:\\') pode potencialmente retornar um resultado diferente de path.resolve('C:'). Para obter mais informações, consulte esta página da MSDN.

`path.basename(path[, suffix])`

[Histórico]

Versão	Mudanças
v6.0.0	Passar algo que não seja uma string como argumento `path` agora lançará um erro.
v0.1.25	Adicionado em: v0.1.25

path <string>
suffix <string> Um sufixo opcional para remover
Retorna: <string>

O método path.basename() retorna a última parte de um path, semelhante ao comando basename do Unix. Separadores de diretório à direita são ignorados.

path.basename('/foo/bar/baz/asdf/quux.html');
// Retorna: 'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html');
// Retorna: 'quux'

Embora o Windows geralmente trate os nomes de arquivos, incluindo as extensões de arquivos, de forma não diferenciada entre maiúsculas e minúsculas, esta função não o faz. Por exemplo, C:\\foo.html e C:\\foo.HTML referem-se ao mesmo arquivo, mas basename trata a extensão como uma string que diferencia maiúsculas de minúsculas:

path.win32.basename('C:\\foo.html', '.html');
// Retorna: 'foo'

path.win32.basename('C:\\foo.HTML', '.html');
// Retorna: 'foo.HTML'

Um TypeError é lançado se path não for uma string ou se suffix for fornecido e não for uma string.

`path.delimiter`

Adicionado em: v0.9.3

<string>

Fornece o delimitador de caminho específico da plataforma:

; para Windows
: para POSIX

Por exemplo, no POSIX:

console.log(process.env.PATH);
// Imprime: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'

process.env.PATH.split(path.delimiter);
// Retorna: ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']

No Windows:

console.log(process.env.PATH);
// Imprime: 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'

process.env.PATH.split(path.delimiter);
// Retorna ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']

`path.dirname(path)`

[Histórico]

Versão	Mudanças
v6.0.0	Passar um não-string como o argumento `path` agora lançará um erro.
v0.1.16	Adicionado em: v0.1.16

path <string>
Retorna: <string>

O método path.dirname() retorna o nome do diretório de um path, semelhante ao comando dirname do Unix. Separadores de diretório à direita são ignorados, veja path.sep.

path.dirname('/foo/bar/baz/asdf/quux');
// Retorna: '/foo/bar/baz/asdf'

Um TypeError é lançado se path não for uma string.

`path.extname(path)`

[Histórico]

Versão	Mudanças
v6.0.0	Passar um não-string como o argumento `path` agora lançará um erro.
v0.1.25	Adicionado em: v0.1.25

path <string>
Retorna: <string>

O método path.extname() retorna a extensão do path, da última ocorrência do caractere . (ponto) até o final da string na última porção do path. Se não houver . na última porção do path, ou se não houver caracteres . além do primeiro caractere do nome base do path (veja path.basename()), uma string vazia é retornada.

path.extname('index.html');
// Retorna: '.html'

path.extname('index.coffee.md');
// Retorna: '.md'

path.extname('index.');
// Retorna: '.'

path.extname('index');
// Retorna: ''

path.extname('.index');
// Retorna: ''

path.extname('.index.md');
// Retorna: '.md'

Um TypeError é lançado se path não for uma string.

`path.format(pathObject)`

[Histórico]

Versão	Mudanças
v19.0.0	O ponto será adicionado se não for especificado em `ext`.
v0.11.15	Adicionado em: v0.11.15

pathObject <Objeto> Qualquer objeto JavaScript que tenha as seguintes propriedades:
- dir <string>
- root <string>
- base <string>
- name <string>
- ext <string>
Retorna: <string>

O método path.format() retorna uma string de caminho de um objeto. Isso é o oposto de path.parse().

Ao fornecer propriedades para o pathObject, lembre-se de que existem combinações em que uma propriedade tem prioridade sobre outra:

pathObject.root é ignorado se pathObject.dir for fornecido
pathObject.ext e pathObject.name são ignorados se pathObject.base existir

Por exemplo, no POSIX:

// Se `dir`, `root` e `base` forem fornecidos,
// `${dir}${path.sep}${base}`
// será retornado. `root` é ignorado.
path.format({
  root: '/ignored',
  dir: '/home/user/dir',
  base: 'file.txt',
});
// Retorna: '/home/user/dir/file.txt'

// `root` será usado se `dir` não for especificado.
// Se apenas `root` for fornecido ou `dir` for igual a `root`, então o
// separador de plataforma não será incluído. `ext` será ignorado.
path.format({
  root: '/',
  base: 'file.txt',
  ext: 'ignored',
});
// Retorna: '/file.txt'

// `name` + `ext` será usado se `base` não for especificado.
path.format({
  root: '/',
  name: 'file',
  ext: '.txt',
});
// Retorna: '/file.txt'

// O ponto será adicionado se não for especificado em `ext`.
path.format({
  root: '/',
  name: 'file',
  ext: 'txt',
});
// Retorna: '/file.txt'

No Windows:

path.format({
  dir: 'C:\\path\\dir',
  base: 'file.txt',
});
// Retorna: 'C:\\path\\dir\\file.txt'

`path.matchesGlob(path, pattern)`

Adicionado em: v22.5.0, v20.17.0

[Estável: 1 - Experimental]

Estável: 1 Estabilidade: 1 - Experimental

path <string> O caminho para correspondência com o glob.
pattern <string> O glob para verificar o caminho.
Retorna: <boolean> Se o path correspondeu ou não ao pattern.

O método path.matchesGlob() determina se path corresponde ao pattern.

Por exemplo:

path.matchesGlob('/foo/bar', '/foo/*'); // true
path.matchesGlob('/foo/bar*', 'foo/bird'); // false

Um TypeError é lançado se path ou pattern não forem strings.

`path.isAbsolute(path)`

Adicionado em: v0.11.2

path <string>
Retorna: <boolean>

O método path.isAbsolute() determina se path é um caminho absoluto.

Se o path fornecido for uma string de comprimento zero, false será retornado.

Por exemplo, em POSIX:

path.isAbsolute('/foo/bar'); // true
path.isAbsolute('/baz/..');  // true
path.isAbsolute('qux/');     // false
path.isAbsolute('.');        // false

No Windows:

path.isAbsolute('//server');    // true
path.isAbsolute('\\\\server');  // true
path.isAbsolute('C:/foo/..');   // true
path.isAbsolute('C:\\foo\\..'); // true
path.isAbsolute('bar\\baz');    // false
path.isAbsolute('bar/baz');     // false
path.isAbsolute('.');           // false

Um TypeError é lançado se path não for uma string.

`path.join([...paths])`

Adicionado em: v0.1.16

...paths <string> Uma sequência de segmentos de caminho
Retorna: <string>

O método path.join() une todos os segmentos de path fornecidos usando o separador específico da plataforma como delimitador, então normaliza o caminho resultante.

Segmentos de path de comprimento zero são ignorados. Se a string de caminho unida for uma string de comprimento zero, então '.' será retornado, representando o diretório de trabalho atual.

path.join('/foo', 'bar', 'baz/asdf', 'quux', '..');
// Retorna: '/foo/bar/baz/asdf'

path.join('foo', {}, 'bar');
// Lança 'TypeError: Path must be a string. Received {}'

Um TypeError é lançado se qualquer um dos segmentos de caminho não for uma string.

`path.normalize(path)`

Adicionado em: v0.1.23

path <string>
Retorna: <string>

O método path.normalize() normaliza o path fornecido, resolvendo segmentos '..' e '.'.

Quando múltiplos caracteres de separação de segmento de caminho sequenciais são encontrados (por exemplo, / em POSIX e \ ou / no Windows), eles são substituídos por uma única instância do separador de segmento de caminho específico da plataforma (/ em POSIX e \ no Windows). Separadores finais são preservados.

Se o path for uma string de comprimento zero, '.' é retornado, representando o diretório de trabalho atual.

Em POSIX, os tipos de normalização aplicados por esta função não aderem estritamente à especificação POSIX. Por exemplo, esta função substituirá duas barras iniciais por uma única barra como se fosse um caminho absoluto regular, enquanto alguns sistemas POSIX atribuem um significado especial a caminhos que começam com exatamente duas barras. Da mesma forma, outras substituições realizadas por esta função, como remover segmentos .., podem alterar a forma como o sistema subjacente resolve o caminho.

Por exemplo, em POSIX:

path.normalize('/foo/bar//baz/asdf/quux/..');
// Retorna: '/foo/bar/baz/asdf'

No Windows:

path.normalize('C:\\temp\\\\foo\\bar\\..\\');
// Retorna: 'C:\\temp\\foo\\'

Como o Windows reconhece múltiplos separadores de caminho, ambos os separadores serão substituídos por instâncias do separador preferido do Windows (\):

path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar');
// Retorna: 'C:\\temp\\foo\\bar'

Um TypeError é lançado se path não for uma string.

`path.parse(path)`

Adicionado em: v0.11.15

path <string>
Retorna: <Object>

O método path.parse() retorna um objeto cujas propriedades representam elementos significativos do path. Separadores de diretório finais são ignorados, consulte path.sep.

O objeto retornado terá as seguintes propriedades:

dir <string>
root <string>
base <string>
name <string>
ext <string>

Por exemplo, em POSIX:

path.parse('/home/user/dir/file.txt');
// Retorna:
// { root: '/',
//   dir: '/home/user/dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

text

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘
(Todos os espaços na linha "" devem ser ignorados. Eles são puramente para formatação.)

No Windows:

path.parse('C:\\path\\dir\\file.txt');
// Retorna:
// { root: 'C:\\',
//   dir: 'C:\\path\\dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

text

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
" C:\      path\dir   \ file  .txt "
└──────┴──────────────┴──────┴─────┘
(Todos os espaços na linha "" devem ser ignorados. Eles são puramente para formatação.)

Um TypeError é lançado se path não for uma string.

`path.posix`

[Histórico]

Versão	Mudanças
v15.3.0	Exposto como `require('path/posix')`.
v0.11.15	Adicionado em: v0.11.15

<Object>

A propriedade path.posix fornece acesso a implementações específicas do POSIX dos métodos path.

A API é acessível através de require('node:path').posix ou require('node:path/posix').

`path.relative(from, to)`

[Histórico]

Versão	Mudanças
v6.8.0	No Windows, as barras iniciais para caminhos UNC agora são incluídas no valor de retorno.
v0.5.0	Adicionado em: v0.5.0

from <string>
to <string>
Retorna: <string>

O método path.relative() retorna o caminho relativo de from para to com base no diretório de trabalho atual. Se from e to forem resolvidos para o mesmo caminho (após chamar path.resolve() em cada um), uma string de comprimento zero é retornada.

Se uma string de comprimento zero for passada como from ou to, o diretório de trabalho atual será usado em vez das strings de comprimento zero.

Por exemplo, no POSIX:

path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb');
// Retorna: '../../impl/bbb'

No Windows:

path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb');
// Retorna: '..\\..\\impl\\bbb'

Um TypeError é lançado se from ou to não for uma string.

`path.resolve([...paths])`

Adicionado em: v0.3.4

...paths <string> Uma sequência de caminhos ou segmentos de caminho
Retorna: <string>

O método path.resolve() resolve uma sequência de caminhos ou segmentos de caminho em um caminho absoluto.

A sequência de caminhos fornecida é processada da direita para a esquerda, com cada path subsequente sendo adicionado até que um caminho absoluto seja construído. Por exemplo, dada a sequência de segmentos de caminho: /foo, /bar, baz, chamar path.resolve('/foo', '/bar', 'baz') retornaria /bar/baz porque 'baz' não é um caminho absoluto, mas '/bar' + '/' + 'baz' é.

Se, após processar todos os segmentos de path fornecidos, um caminho absoluto ainda não tiver sido gerado, o diretório de trabalho atual será usado.

O caminho resultante é normalizado e as barras finais são removidas, a menos que o caminho seja resolvido para o diretório raiz.

Segmentos de path de comprimento zero são ignorados.

Se nenhum segmento de path for passado, path.resolve() retornará o caminho absoluto do diretório de trabalho atual.

path.resolve('/foo/bar', './baz');
// Retorna: '/foo/bar/baz'

path.resolve('/foo/bar', '/tmp/file/');
// Retorna: '/tmp/file'

path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif');
// Se o diretório de trabalho atual for /home/myself/node,
// isso retorna '/home/myself/node/wwwroot/static_files/gif/image.gif'

Um TypeError é lançado se algum dos argumentos não for uma string.

`path.sep`

Adicionado em: v0.7.9

<string>

Fornece o separador de segmento de caminho específico da plataforma:

\ no Windows
/ no POSIX

Por exemplo, no POSIX:

'foo/bar/baz'.split(path.sep);
// Retorna: ['foo', 'bar', 'baz']

No Windows:

'foo\\bar\\baz'.split(path.sep);
// Retorna: ['foo', 'bar', 'baz']

No Windows, tanto a barra (/) quanto a barra invertida (\) são aceitas como separadores de segmento de caminho; no entanto, os métodos path adicionam apenas barras invertidas (\).

`path.toNamespacedPath(path)`

Adicionado em: v9.0.0

path <string>
Retorna: <string>

Apenas em sistemas Windows, retorna um caminho com prefixo de namespace equivalente para o path fornecido. Se path não for uma string, path será retornado sem modificações.

Este método é significativo apenas em sistemas Windows. Em sistemas POSIX, o método não é operacional e sempre retorna path sem modificações.

`path.win32`

[Histórico]

Versão	Mudanças
v15.3.0	Exposto como `require('path/win32')`.
v0.11.15	Adicionado em: v0.11.15

<Object>

A propriedade path.win32 fornece acesso a implementações específicas do Windows dos métodos path.

A API é acessível via require('node:path').win32 ou require('node:path/win32').

Path ​

Windows vs. POSIX ​

path.basename(path[, suffix]) ​

path.delimiter ​

path.dirname(path) ​

path.extname(path) ​

path.format(pathObject) ​

path.matchesGlob(path, pattern) ​

path.isAbsolute(path) ​

path.join([...paths]) ​

path.normalize(path) ​

path.parse(path) ​

path.posix ​

path.relative(from, to) ​

path.resolve([...paths]) ​

path.sep ​

path.toNamespacedPath(path) ​

path.win32 ​

Path

Windows vs. POSIX

`path.basename(path[, suffix])`

`path.delimiter`

`path.dirname(path)`

`path.extname(path)`

`path.format(pathObject)`

`path.matchesGlob(path, pattern)`

`path.isAbsolute(path)`

`path.join([...paths])`

`path.normalize(path)`

`path.parse(path)`

`path.posix`

`path.relative(from, to)`

`path.resolve([...paths])`

`path.sep`

`path.toNamespacedPath(path)`

`path.win32`