Path

[Estável: 2 - Estável]

Estável: 2 Estabilidade: 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:

CJS

const path = require('node:path')

ESM

import path from 'node:path'

Windows vs. POSIX

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

Portanto, usar path.basename() pode gerar resultados diferentes em POSIX e Windows:

Em 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 arquivo do Windows em qualquer sistema operacional, use path.win32:

Em POSIX e Windows:

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

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

Em POSIX e 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 mais informações, consulte esta página da MSDN.

path.basename(path[, suffix])

[Histórico]

Versão	Alterações
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>
• suffix <string> Um sufixo opcional para remover
• Retorna: <string>

O método path.basename() retorna a última parte de um path, semelhante ao comando Unix basename. Separadores de diretório [/api/path#pathsep] à 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 nomes de arquivos, incluindo extensões de arquivo, de forma não sensível a maiúsculas e minúsculas, esta função não o faz. Por exemplo, C:\\foo.html e C:\\foo.HTML se referem 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, em 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 valor que não seja uma string como 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, similar ao comando Unix dirname. Separadores de diretório finais 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 valor que não seja uma string como 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 parte do path. Se não houver . na última parte do path, ou se não houver caracteres . além do primeiro caractere do nome base de 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 com 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 a partir de um objeto. Este é 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: '/ignorado',
  dir: '/home/usuario/dir',
  base: 'arquivo.txt',
})
// Retorna: '/home/usuario/dir/arquivo.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: 'arquivo.txt',
  ext: 'ignorado',
})
// Retorna: '/arquivo.txt'

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

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

No Windows:

path.format({
  dir: 'C:\\caminho\\dir',
  base: 'arquivo.txt',
})
// Retorna: 'C:\\caminho\\dir\\arquivo.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 corresponder ao glob.
• pattern <string> O glob para verificar o caminho em relação.
• Retorna: <boolean> Se o path correspondeu ou não ao pattern.

O método path.matchesGlob() determina se o 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 um delimitador e, em seguida, 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 algum 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 são encontrados múltiplos caracteres de separação de segmento de caminho sequenciais (por exemplo, / em POSIX e \ ou / em Windows), eles são substituídos por uma única instância do separador de segmento de caminho específico da plataforma (/ em POSIX e \ em 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 a remoção de 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'

Em Windows:

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

Como o Windows reconhece vários 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, veja 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' }

┌─────────────────────┬────────────┐
│          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.)

Em Windows:

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

┌─────────────────────┬────────────┐
│          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 via 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 estã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, em 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 forem strings.

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 fornecida de caminhos é processada da direita para a esquerda, com cada path subsequente 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').