@jsenv/url-meta

url-meta

Associate data to urls using patterns.

Presentation

@jsenv/url-meta allows to associate value to urls using pattern matching.

import { urlToMeta } from "@jsenv/url-meta"

// conditionally associates url and values
const structuredMetaMap = {
  color: {
    "file:///*": "black",
    "file:///*.js": "red",
  },
}

const urlToColor = (url) => {
  return urlToMeta({ url, structuredMetaMap }).color
}

console.log(`file.json color is ${urlToColor("file:///file.json")}`)
console.log(`file.js color is ${urlToColor("file:///file.js")}`)

Code above logs

file.json color is black
file.js color is red

Common pattern example

pattern	Description
**/	Everything
*/**/	Inside a directory
**/.*/	Inside directory starting with a dot
**/node_modules/	Inside any node_modules directory
node_modules/	Inside root node_modules directory
**/*.map	Ending with .map
**/*.test.*	Contains .test.
*	Inside the root directory only
*/*	Inside a directory of depth 1

Pattern matching example

Table showing if a pattern matches when applied to "file:///directory/file.js"

pattern	matches?
file:///directory/*.js	true
file:///directory/**/*.js	true
file:///**/*.js	true
file:///directory	false
file:///directory/	true
file:///directory/file.js	true
file:///directory/file.jsx	false

metaMap and structuredMetaMap

metaMap and structuredMetaMap below translates into: "files are visible except thoose in .git/ directory"

const metaMap = {
  "**/*": { visible: true },
  "**/.git/": { visible: false },
}

const structuredMetaMap = {
  visible: {
    "**/*/": true,
    "**/.git/": false,
  },
}

structuredMetaMap allows to group patterns per property which are easier to read and compose. For this reason it's the object structure used by our API.

applyPatternMatching

applyPatternMatching is a function returning a matchResult indicating if and how a pattern matches an url.

import { applyPatternMatching } from "@jsenv/url-meta"

const matchResult = applyPatternMatching({
  pattern: "file:///**/*",
  url: "file://Users/directory/file.js",
})

matchResult.matched // true

pattern

pattern parameter is a string looking like an url but where * and ** can be used so that one specifier can match several url. This parameter is required.

url

url parameter is a string representing a url. This parameter is required.

matchResult

matchResult represents if and how a pattern matches an url.

const fullMatch = applyPatternMatching({
  pattern: "file:///**/*",
  url: "file://Users/directory/file.js",
})
fullMatch // { matched: true, index: 31, patternIndex: 12 }

fullMatch object indicates pattern fully matched url.

const partialMatch = applyPatternMatching({
  pattern: "file:///*.js",
  url: "file:///file.jsx",
})
partialMatch // { matched: false, index: 14, patternIndex: 14 }

partialMatch object indicates pattern matched url until comparing url[14] with pattern[14].

normalizeStructuredMetaMap

normalizeStructuredMetaMap is a function resolving a structuredMetaMap against an url.

import { normalizeStructuredMetaMap } from "@jsenv/url-meta"

const structuredMetaMapNormalized = normalizeStructuredMetaMap(
  {
    visible: {
      "**/*/": true,
      "**/.git/": false,
    },
  },
  "file:///Users/directory/",
)
console.log(JSON.stringify(structuredMetaMapNormalized, null, "  "))

{
  "visible": {
    "file:///Users/directory/**/*/": true,
    "file:///Users/directory/**/.git/": false
  }
}

urlCanContainsMetaMatching

urlCanContainsMetaMatching is a function designed to ignore directory content that would never have specific metas.

import { urlCanContainsMetaMatching } from "@jsenv/url-meta"

const structuredMetaMap = {
  color: {
    "file:///**/*": "blue",
    "file:///**/node_modules/": "green",
  },
}

const firstUrlCanHaveFilesWithColorBlue = urlCanContainsMetaMatching({
  url: "file:///src/",
  specifierMetaMap,
  predicate: ({ color }) => color === "blue",
})
firstUrlCanHaveFilesWithColorBlue // true

const secondUrlCanHaveFileWithColorBlue = urlCanContainsMetaMatching({
  url: "file:///node_modules/src/",
  specifierMetaMap,
  predicate: ({ color }) => color === "blue",
})
secondUrlCanHaveFileWithColorBlue // false

urlToMeta

urlToMeta is a function returning an object being the composition of all meta where pattern matched the url.

import { urlToMeta } from "@jsenv/url-meta"

const structuredMetaMap = {
  insideSrc: {
    "file:///src/": true,
  },
  extensionIsJs: {
    "file:///**/*.js": true,
  },
}

const urlA = "file:///src/file.js"
const urlB = "file:///src/file.json"

console.log(
  `${urlA}: ${JSON.stringify(
    urlToMeta({ url: urlA, specifierMetaMap }),
    null,
    "  ",
  )}`,
)
console.log(
  `${urlB}: ${JSON.stringify(
    urlToMeta({ url: urlB, specifierMetaMap }),
    null,
    "  ",
  )}`,
)

Console output

file:///src/file.js: {
  "insideSrc": true,
  "extensionIsJs": true,
}
file:///src/file.json: {
  "insideSrc": true
}

Installation

npm install @jsenv/url-meta

Can be used in browsers and Node.js.