@jsenv/urls 1.0.0

package/src/meta/pattern_matching.js

@@ -0,0 +1,245 @@
+/*
+ * Link to things doing pattern matching:
+ * https://git-scm.com/docs/gitignore
+ * https://github.com/kaelzhang/node-ignore
+ */
+
+import { assertUrlLike } from "./assertions.js"
+
+/** @module jsenv_url_meta **/
+/**
+ * An object representing the result of applying a pattern to an url
+ * @typedef {Object} MatchResult
+ * @property {boolean} matched Indicates if url matched pattern
+ * @property {number} patternIndex Index where pattern stopped matching url, otherwise pattern.length
+ * @property {number} urlIndex Index where url stopped matching pattern, otherwise url.length
+ * @property {Array} matchGroups Array of strings captured during pattern matching
+ */
+
+/**
+ * Apply a pattern to an url
+ * @param {Object} applyPatternMatchingParams
+ * @param {string} applyPatternMatchingParams.pattern "*", "**" and trailing slash have special meaning
+ * @param {string} applyPatternMatchingParams.url a string representing an url
+ * @return {MatchResult}
+ */
+export const applyPatternMatching = ({ url, pattern }) => {
+  assertUrlLike(pattern, "pattern")
+  assertUrlLike(url, "url")
+  const { matched, patternIndex, index, groups } = applyMatching(pattern, url)
+  const matchGroups = []
+  let groupIndex = 0
+  groups.forEach((group) => {
+    if (group.name) {
+      matchGroups[group.name] = group.string
+    } else {
+      matchGroups[groupIndex] = group.string
+      groupIndex++
+    }
+  })
+  return {
+    matched,
+    patternIndex,
+    urlIndex: index,
+    matchGroups,
+  }
+}
+
+const applyMatching = (pattern, string) => {
+  const groups = []
+  let patternIndex = 0
+  let index = 0
+  let remainingPattern = pattern
+  let remainingString = string
+  let restoreIndexes = true
+
+  const consumePattern = (count) => {
+    const subpattern = remainingPattern.slice(0, count)
+    remainingPattern = remainingPattern.slice(count)
+    patternIndex += count
+    return subpattern
+  }
+  const consumeString = (count) => {
+    const substring = remainingString.slice(0, count)
+    remainingString = remainingString.slice(count)
+    index += count
+    return substring
+  }
+  const consumeRemainingString = () => {
+    return consumeString(remainingString.length)
+  }
+
+  let matched
+  const iterate = () => {
+    const patternIndexBefore = patternIndex
+    const indexBefore = index
+    matched = matchOne()
+    if (matched === undefined) {
+      consumePattern(1)
+      consumeString(1)
+      iterate()
+      return
+    }
+    if (matched === false && restoreIndexes) {
+      patternIndex = patternIndexBefore
+      index = indexBefore
+    }
+  }
+  const matchOne = () => {
+    // pattern consumed and string consumed
+    if (remainingPattern === "" && remainingString === "") {
+      return true // string fully matched pattern
+    }
+    // pattern consumed, string not consumed
+    if (remainingPattern === "" && remainingString !== "") {
+      return false // fails because string longer than expected
+    }
+    // -- from this point pattern is not consumed --
+    // string consumed, pattern not consumed
+    if (remainingString === "") {
+      if (remainingPattern === "**") {
+        // trailing "**" is optional
+        consumePattern(2)
+        return true
+      }
+      if (remainingPattern === "*") {
+        groups.push({ string: "" })
+      }
+      return false // fail because string shorter than expected
+    }
+    // -- from this point pattern and string are not consumed --
+    // fast path trailing slash
+    if (remainingPattern === "/") {
+      if (remainingString[0] === "/") {
+        // trailing slash match remaining
+        consumePattern(1)
+        groups.push({ string: consumeRemainingString() })
+        return true
+      }
+      return false
+    }
+    // fast path trailing '**'
+    if (remainingPattern === "**") {
+      consumePattern(2)
+      consumeRemainingString()
+      return true
+    }
+    // pattern leading **
+    if (remainingPattern.slice(0, 2) === "**") {
+      consumePattern(2) // consumes "**"
+      if (remainingPattern[0] === "/") {
+        consumePattern(1) // consumes "/"
+      }
+      // pattern ending with ** always match remaining string
+      if (remainingPattern === "") {
+        consumeRemainingString()
+        return true
+      }
+      const skipResult = skipUntilMatch({
+        pattern: remainingPattern,
+        string: remainingString,
+        canSkipSlash: true,
+      })
+      groups.push(...skipResult.groups)
+      consumePattern(skipResult.patternIndex)
+      consumeRemainingString()
+      restoreIndexes = false
+      return skipResult.matched
+    }
+    if (remainingPattern[0] === "*") {
+      consumePattern(1) // consumes "*"
+      if (remainingPattern === "") {
+        // matches everything except '/'
+        const slashIndex = remainingString.indexOf("/")
+        if (slashIndex === -1) {
+          groups.push({ string: consumeRemainingString() })
+          return true
+        }
+        groups.push({ string: consumeString(slashIndex) })
+        return false
+      }
+      // the next char must not the one expected by remainingPattern[0]
+      // because * is greedy and expect to skip at least one char
+      if (remainingPattern[0] === remainingString[0]) {
+        groups.push({ string: "" })
+        patternIndex = patternIndex - 1
+        return false
+      }
+      const skipResult = skipUntilMatch({
+        pattern: remainingPattern,
+        string: remainingString,
+        canSkipSlash: false,
+      })
+      groups.push(skipResult.group, ...skipResult.groups)
+      consumePattern(skipResult.patternIndex)
+      consumeString(skipResult.index)
+      restoreIndexes = false
+      return skipResult.matched
+    }
+    if (remainingPattern[0] !== remainingString[0]) {
+      return false
+    }
+    return undefined
+  }
+  iterate()
+
+  return {
+    matched,
+    patternIndex,
+    index,
+    groups,
+  }
+}
+
+const skipUntilMatch = ({ pattern, string, canSkipSlash }) => {
+  let index = 0
+  let remainingString = string
+  let longestMatchRange = null
+  const tryToMatch = () => {
+    const matchAttempt = applyMatching(pattern, remainingString)
+    if (matchAttempt.matched) {
+      return {
+        matched: true,
+        patternIndex: matchAttempt.patternIndex,
+        index: index + matchAttempt.index,
+        groups: matchAttempt.groups,
+        group: {
+          string:
+            remainingString === ""
+              ? string
+              : string.slice(0, -remainingString.length),
+        },
+      }
+    }
+    const matchAttemptIndex = matchAttempt.index
+    const matchRange = {
+      patternIndex: matchAttempt.patternIndex,
+      index,
+      length: matchAttemptIndex,
+      groups: matchAttempt.groups,
+    }
+    if (!longestMatchRange || longestMatchRange.length < matchRange.length) {
+      longestMatchRange = matchRange
+    }
+    const nextIndex = matchAttemptIndex + 1
+    const canSkip =
+      nextIndex < remainingString.length &&
+      (canSkipSlash || remainingString[0] !== "/")
+    if (canSkip) {
+      // search against the next unattempted string
+      index += nextIndex
+      remainingString = remainingString.slice(nextIndex)
+      return tryToMatch()
+    }
+    return {
+      matched: false,
+      patternIndex: longestMatchRange.patternIndex,
+      index: longestMatchRange.index + longestMatchRange.length,
+      groups: longestMatchRange.groups,
+      group: {
+        string: string.slice(0, longestMatchRange.index),
+      },
+    }
+  }
+  return tryToMatch()
+}

package/src/meta/resolve_associations.js

@@ -0,0 +1,25 @@
+import { assertUrlLike } from "./assertions.js"
+
+export const resolveAssociations = (associations, baseUrl) => {
+  assertUrlLike(baseUrl, "baseUrl")
+  const associationsResolved = {}
+  Object.keys(associations).forEach((key) => {
+    const valueMap = associations[key]
+    const valueMapResolved = {}
+    Object.keys(valueMap).forEach((pattern) => {
+      const value = valueMap[pattern]
+      const patternResolved = normalizeUrlPattern(pattern, baseUrl)
+      valueMapResolved[patternResolved] = value
+    })
+    associationsResolved[key] = valueMapResolved
+  })
+  return associationsResolved
+}
+
+const normalizeUrlPattern = (urlPattern, baseUrl) => {
+  // starts with a scheme
+  if (/^[a-zA-Z]{2,}:/.test(urlPattern)) {
+    return urlPattern
+  }
+  return String(new URL(urlPattern, baseUrl))
+}

package/src/meta/url_child_may_match.js

@@ -0,0 +1,47 @@
+import { assertUrlLike, isPlainObject } from "./assertions.js"
+import { asFlatAssociations } from "./as_flat_associations.js"
+import { applyPatternMatching } from "./pattern_matching.js"
+
+export const urlChildMayMatch = ({ url, associations, predicate }) => {
+  assertUrlLike(url, "url")
+  // the function was meants to be used on url ending with '/'
+  if (!url.endsWith("/")) {
+    throw new Error(`url should end with /, got ${url}`)
+  }
+  if (typeof predicate !== "function") {
+    throw new TypeError(`predicate must be a function, got ${predicate}`)
+  }
+  const flatAssociations = asFlatAssociations(associations)
+  // for full match we must create an object to allow pattern to override previous ones
+  let fullMatchMeta = {}
+  let someFullMatch = false
+  // for partial match, any meta satisfying predicate will be valid because
+  // we don't know for sure if pattern will still match for a file inside pathname
+  const partialMatchMetaArray = []
+  Object.keys(flatAssociations).forEach((pattern) => {
+    const value = flatAssociations[pattern]
+    const matchResult = applyPatternMatching({
+      pattern,
+      url,
+    })
+    if (matchResult.matched) {
+      someFullMatch = true
+      if (isPlainObject(fullMatchMeta) && isPlainObject(value)) {
+        fullMatchMeta = {
+          ...fullMatchMeta,
+          ...value,
+        }
+      } else {
+        fullMatchMeta = value
+      }
+    } else if (someFullMatch === false && matchResult.urlIndex >= url.length) {
+      partialMatchMetaArray.push(value)
+    }
+  })
+  if (someFullMatch) {
+    return Boolean(predicate(fullMatchMeta))
+  }
+  return partialMatchMetaArray.some((partialMatchMeta) =>
+    predicate(partialMatchMeta),
+  )
+}

package/src/meta/url_meta.js

@@ -0,0 +1,13 @@
+import { resolveAssociations } from "./resolve_associations.js"
+import { applyAssociations } from "./associations.js"
+import { applyAliases } from "./aliases.js"
+import { applyPatternMatching } from "./pattern_matching.js"
+import { urlChildMayMatch } from "./url_child_may_match.js"
+
+export const URL_META = {
+  resolveAssociations,
+  applyAssociations,
+  urlChildMayMatch,
+  applyPatternMatching,
+  applyAliases,
+}

package/src/url_trace.js

@@ -0,0 +1,229 @@
+// consider switching to https://babeljs.io/docs/en/babel-code-frame
+// https://github.com/postcss/postcss/blob/fd30d3df5abc0954a0ec642a3cdc644ab2aacf9c/lib/css-syntax-error.js#L43
+// https://github.com/postcss/postcss/blob/fd30d3df5abc0954a0ec642a3cdc644ab2aacf9c/lib/terminal-highlight.js#L50
+// https://github.com/babel/babel/blob/eea156b2cb8deecfcf82d52aa1b71ba4995c7d68/packages/babel-code-frame/src/index.js#L1
+
+import { urlToFileSystemPath } from "@jsenv/filesystem"
+import { ANSI } from "@jsenv/log"
+
+export const stringifyUrlTrace = (trace) => {
+  let string = ""
+  trace.forEach(({ type, url, line, column, source }, index) => {
+    if (index === 0) {
+      string += stringifyUrlSite({ url, line, column, source })
+      return
+    }
+
+    if (type === "import") {
+      string += `\n  imported by ${stringifyUrlSite({
+        url,
+        line,
+        column,
+      })}`
+      return
+    }
+
+    string += `\n  referenced by ${stringifyUrlSite({
+      url,
+      line,
+      column,
+    })}`
+  }, "")
+
+  return string
+}
+
+export const stringifyUrlSite = (
+  { url, line, column, content },
+  {
+    showCodeFrame = true,
+    numberOfSurroundingLinesToShow,
+    lineMaxLength,
+    color,
+  } = {},
+) => {
+  let string = `${humanizeUrl(url)}`
+
+  if (typeof line === "number") {
+    string += `:${line}`
+    if (typeof column === "number") {
+      string += `:${column}`
+    }
+  }
+
+  if (!showCodeFrame || typeof line !== "number" || !content) {
+    return string
+  }
+
+  const sourceLoc = showSourceLocation({
+    content,
+    line,
+    column,
+    numberOfSurroundingLinesToShow,
+    lineMaxLength,
+    color,
+  })
+
+  return `${string}
+${sourceLoc}`
+}
+
+export const humanizeUrl = (url) => {
+  if (url.startsWith("file://")) {
+    // we prefer file system path because vscode reliably make them clickable
+    // and sometimes it won't for file:// urls
+    return urlToFileSystemPath(url)
+  }
+  return url
+}
+
+export const showSourceLocation = ({
+  content,
+  line,
+  column,
+  numberOfSurroundingLinesToShow = 1,
+  lineMaxLength = 120,
+  color = false,
+} = {}) => {
+  let mark = (string) => string
+  let aside = (string) => string
+  if (color) {
+    mark = (string) => ANSI.color(string, ANSI.RED)
+    aside = (string) => ANSI.color(string, ANSI.GREY)
+  }
+
+  const lines = content.split(/\r?\n/)
+  if (line === 0) line = 1
+  let lineRange = {
+    start: line - 1,
+    end: line,
+  }
+  lineRange = moveLineRangeUp(lineRange, numberOfSurroundingLinesToShow)
+  lineRange = moveLineRangeDown(lineRange, numberOfSurroundingLinesToShow)
+  lineRange = lineRangeWithinLines(lineRange, lines)
+  const linesToShow = lines.slice(lineRange.start, lineRange.end)
+  const endLineNumber = lineRange.end
+  const lineNumberMaxWidth = String(endLineNumber).length
+
+  if (column === 0) column = 1
+
+  const columnRange = {}
+  if (column === undefined) {
+    columnRange.start = 0
+    columnRange.end = lineMaxLength
+  } else if (column > lineMaxLength) {
+    columnRange.start = column - Math.floor(lineMaxLength / 2)
+    columnRange.end = column + Math.ceil(lineMaxLength / 2)
+  } else {
+    columnRange.start = 0
+    columnRange.end = lineMaxLength
+  }
+
+  return linesToShow.map((lineSource, index) => {
+    const lineNumber = lineRange.start + index + 1
+    const isMainLine = lineNumber === line
+    const lineSourceTruncated = applyColumnRange(columnRange, lineSource)
+    const lineNumberWidth = String(lineNumber).length
+    // ensure if line moves from 7,8,9 to 10 the display is still great
+    const lineNumberRightSpacing = " ".repeat(
+      lineNumberMaxWidth - lineNumberWidth,
+    )
+    const asideSource = `${lineNumber}${lineNumberRightSpacing} |`
+    const lineFormatted = `${aside(asideSource)} ${lineSourceTruncated}`
+    if (isMainLine) {
+      if (column === undefined) {
+        return `${mark(">")} ${lineFormatted}`
+      }
+      const spacing = stringToSpaces(
+        `${asideSource} ${lineSourceTruncated.slice(
+          0,
+          column - columnRange.start - 1,
+        )}`,
+      )
+      return `${mark(">")} ${lineFormatted}
+  ${spacing}${mark("^")}`
+    }
+    return `  ${lineFormatted}`
+  }).join(`
+`)
+}
+
+const applyColumnRange = ({ start, end }, line) => {
+  if (typeof start !== "number") {
+    throw new TypeError(`start must be a number, received ${start}`)
+  }
+  if (typeof end !== "number") {
+    throw new TypeError(`end must be a number, received ${end}`)
+  }
+  if (end < start) {
+    throw new Error(
+      `end must be greater than start, but ${end} is smaller than ${start}`,
+    )
+  }
+
+  const prefix = "…"
+  const suffix = "…"
+  const lastIndex = line.length
+
+  if (line.length === 0) {
+    // don't show any ellipsis if the line is empty
+    // because it's not truncated in that case
+    return ""
+  }
+
+  const startTruncated = start > 0
+  const endTruncated = lastIndex > end
+
+  let from = startTruncated ? start + prefix.length : start
+  let to = endTruncated ? end - suffix.length : end
+  if (to > lastIndex) to = lastIndex
+
+  if (start >= lastIndex || from === to) {
+    return ""
+  }
+
+  let result = ""
+  while (from < to) {
+    result += line[from]
+    from++
+  }
+
+  if (result.length === 0) {
+    return ""
+  }
+  if (startTruncated && endTruncated) {
+    return `${prefix}${result}${suffix}`
+  }
+  if (startTruncated) {
+    return `${prefix}${result}`
+  }
+  if (endTruncated) {
+    return `${result}${suffix}`
+  }
+  return result
+}
+
+const stringToSpaces = (string) => string.replace(/[^\t]/g, " ")
+
+// const getLineRangeLength = ({ start, end }) => end - start
+
+const moveLineRangeUp = ({ start, end }, number) => {
+  return {
+    start: start - number,
+    end,
+  }
+}
+
+const moveLineRangeDown = ({ start, end }, number) => {
+  return {
+    start,
+    end: end + number,
+  }
+}
+
+const lineRangeWithinLines = ({ start, end }, lines) => {
+  return {
+    start: start < 0 ? 0 : start,
+    end: end > lines.length ? lines.length : end,
+  }
+}

package/src/url_utils.js

@@ -0,0 +1,107 @@
+import { urlToOrigin, urlToExtension, urlToRessource } from "@jsenv/filesystem"
+
+export const asUrlWithoutSearch = (url) => {
+  const urlObject = new URL(url)
+  urlObject.search = ""
+  return urlObject.href
+}
+
+export const isValidUrl = (url) => {
+  try {
+    // eslint-disable-next-line no-new
+    new URL(url)
+    return true
+  } catch (e) {
+    return false
+  }
+}
+
+// normalize url search params:
+// Using URLSearchParams to alter the url search params
+// can result into "file:///file.css?css_module"
+// becoming "file:///file.css?css_module="
+// we want to get rid of the "=" and consider it's the same url
+export const normalizeUrl = (url) => {
+  if (url.includes("?")) {
+    // disable on data urls (would mess up base64 encoding)
+    if (url.startsWith("data:")) {
+      return url
+    }
+    return url.replace(/[=](?=&|$)/g, "")
+  }
+  return url
+}
+
+export const injectQueryParamsIntoSpecifier = (specifier, params) => {
+  if (isValidUrl(specifier)) {
+    return injectQueryParams(specifier, params)
+  }
+  const [beforeQuestion, afterQuestion = ""] = specifier.split("?")
+  const searchParams = new URLSearchParams(afterQuestion)
+  Object.keys(params).forEach((key) => {
+    searchParams.set(key, params[key])
+  })
+  const paramsString = searchParams.toString()
+  if (paramsString) {
+    return `${beforeQuestion}?${paramsString}`
+  }
+  return specifier
+}
+
+export const injectQueryParams = (url, params) => {
+  const urlObject = new URL(url)
+  Object.keys(params).forEach((key) => {
+    urlObject.searchParams.set(key, params[key])
+  })
+  const urlWithParams = urlObject.href
+  return urlWithParams
+}
+
+export const setUrlExtension = (url, extension) => {
+  const origin = urlToOrigin(url)
+  const currentExtension = urlToExtension(url)
+  const ressource = urlToRessource(url)
+  const [pathname, search] = ressource.split("?")
+  const pathnameWithoutExtension = currentExtension
+    ? pathname.slice(0, -currentExtension.length)
+    : pathname
+  const newPathname = `${pathnameWithoutExtension}${extension}`
+  return `${origin}${newPathname}${search ? `?${search}` : ""}`
+}
+
+export const setUrlFilename = (url, filename) => {
+  const urlObject = new URL(url)
+  let { origin, search, hash } = urlObject
+  // origin is "null" for "file://" urls with Node.js
+  if (origin === "null" && urlObject.href.startsWith("file:")) {
+    origin = "file://"
+  }
+  const parentPathname = new URL("./", urlObject).pathname
+  return `${origin}${parentPathname}${filename}${search}${hash}`
+}
+
+export const ensurePathnameTrailingSlash = (url) => {
+  const urlObject = new URL(url)
+  const { pathname } = urlObject
+  if (pathname.endsWith("/")) {
+    return url
+  }
+  let { origin } = urlObject
+  // origin is "null" for "file://" urls with Node.js
+  if (origin === "null" && urlObject.href.startsWith("file:")) {
+    origin = "file://"
+  }
+  const { search, hash } = urlObject
+  return `${origin}${pathname}/${search}${hash}`
+}
+
+export const asUrlUntilPathname = (url) => {
+  const urlObject = new URL(url)
+  let { origin, pathname } = urlObject
+  // origin is "null" for "file://" urls with Node.js
+  if (origin === "null" && urlObject.href.startsWith("file:")) {
+    origin = "file://"
+  }
+  const urlUntilPathname = `${origin}${pathname}`
+  return urlUntilPathname
+}

package/src/windows_file_path_utils.js

@@ -0,0 +1,16 @@
+export const startsWithWindowsDriveLetter = (string) => {
+  const firstChar = string[0]
+  if (!/[a-zA-Z]/.test(firstChar)) return false
+
+  const secondChar = string[1]
+  if (secondChar !== ":") return false
+
+  return true
+}
+
+export const windowsFilePathToUrl = (windowsFilePath) => {
+  return `file:///${replaceBackSlashesWithSlashes(windowsFilePath)}`
+}
+
+export const replaceBackSlashesWithSlashes = (string) =>
+  string.replace(/\\/g, "/")