@jsenv/url-meta

url-meta

Associate data to urls using patterns.

Table of contents

• Presentation
• Installation
• Documentation
  • Pattern matching behaviour
  • applySpecifierPatternMatching
  • metaMapToSpecifierMetaMap
  • normalizeSpecifierMetaMap
  • urlCanContainsMetaMatching
  • urlToMeta

Presentation

@jsenv/url-meta can be used to associate value to urls. You can associate a value to many urls using pattern matching.

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

// note how specifierMetaMap object below associates object to urls
const specifierMetaMap = {
  "http://example.com/*": {
    color: "black",
  },
  "http://example.com/*.js": {
    color: "red",
  },
}

const urlA = "http://example.com/file.json"
const urlAMeta = urlToMeta({ specifierMetaMap, url: urlA }).color
const urlB = "http://example.com/file.js"
const urlBMeta = urlToMeta({ specifierMetaMap, url: urlB }).color

console.log(`${urlA} color is ${urlAMeta.color}`)
console.log(`${urlB} color is ${urlBMeta.color}`)

Code above logs

http://example.com/file.json color is black
http://example.com/file.js color is red

Installation

npm install @jsenv/url-meta@5.1.1

Documentation

Pattern matching behaviour

The table below gives an idea of how pattern matching behaves.

specifier	url	matches
http://example.com/whatever	http://example.com/whatever/file.js	false
http://example.com/whatever/	http://example.com/whatever/file.js	true
http://example.com/whatever/*.js	http://example.com/whatever/file.js	true
http://example.com/whatever/**/*.js	http://example.com/whatever/file.js	true
http://example.com/**/*.js	http://example.com/whatever/file.js	true
http://example.com/whatever/file.js	http://example.com/whatever/file.js	true
http://example.com/whatever/file.jsx	http://example.com/whatever/file.js	false

applySpecifierPatternMatching

applySpecifierPatternMatching is a function returning a matchResult indicating if and how a specifier matches an url.

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

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

matchResult.matched // true

— source code at src/createLogger.js.

specifier

specifier 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 specifier matches url. It is returned by applySpecifierPatternMatching.

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

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

fullMatch object indicates specifier fully matched url.
partialMatch object indicates specifier matched url until comparing url[14] with specifier[14].

---

metaMapToSpecifierMetaMap

metaMapToSpecifierMetaMap is a function used to convert a metaMap into a specifierMetaMap.

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

metaMapToSpecifierMetaMap({
  show: {
    "file:///**/*": "yes",
    "file://**/.git/": "no",
  },
  format: {
    "file:///**/*.js": "yes",
    "file:///**/*.json": "yes",
    "file://**/.git/": "no",
  },
})

Returns

{
  "file:///**/*": { show: "yes" },
  "file://**/.git": { show: "no", format: "no" },
  "file:///**/*.js": { show: "yes", format: "yes" },
  "file:///**/*.json": { show: "yes", format: "yes" },
}

— source code at src/metaMapToSpecifierMetaMap.js.

metaMap

metaMap parameter is an object where values are conditionnaly applied by specifiers. This parameter is required.

specifierMetaMap

specifierMetaMap is an object where meta (other objects) are conditionnaly applied by specifier. It is returned by metaMapToSpecifierMetaMap.

---

normalizeSpecifierMetaMap

normalizeSpecifierMetaMap is a function resolving specifierMetaMap keys against an url.

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

const specifierMetaMapNormalized = normalizeSpecifierMetaMap(
  {
    "./**/*/": { visible: true },
    "./**/.git/": { visible: false },
  },
  "file:///Users/directory/",
)

— source code at src/normalizeSpecifierMetaMap.js.

---

urlCanContainsMetaMatching

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

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

const specifierMetaMap = {
  "file:///**/*": {
    color: "blue",
  },
  "file:///**/node_modules": {
    color: "green",
  },
}
const bluePredicate = ({ color }) => color === "blue"

const urlA = "file:///src/"
const urlACan = urlCanContainsMetaMatching({
  url: urlA,
  specifierMetaMap,
  predicate: bluePredicate,
})
const urlB = "file:///node_modules/src/"
const urlBCan = urlCanContainsMetaMatching({
  url: urlB,
  specifierMetaMap,
  predicate: bluePredicate,
})

console.log(`${urlA} can contains meta matching blue predicate: ${urlACan}`)
console.log(`${urlB} can contains meta matching blue predicate: ${urlBCan}`)

Console output

file:///src/ can contains meta matching blue predicate: true
file:///node_modules/src/ can contains meta matching blue predicate: false

— source code at src/urlCanContainsMetaMatching.js.

---

urlToMeta

urlToMeta is a function returning an object being the composition of all object associated with a matching specifier.

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

const specifierMetaMap = {
  "file:///src/": {
    insideSrc: true,
  },
  "file:///**/*.js": {
    extensionIsJs: 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
}

— source code at src/urlToMeta.js.