@jsenv/urls 1.0.0

package/docs/url_meta/advanced.md

@@ -0,0 +1,28 @@
+# urlChildMayMatch
+
+_urlChildMayMatch_ is a function designed to ignore directory content that would never have specific metas.
+
+```js
+import { URL_META } from "@jsenv/urls"
+
+const associations = {
+  color: {
+    "file:///**/*": "blue",
+    "file:///**/node_modules/": "green",
+  },
+}
+
+const firstUrlCanHaveFilesWithColorBlue = URL_META.urlChildMayMatch({
+  url: "file:///src/",
+  associations,
+  predicate: ({ color }) => color === "blue",
+})
+firstUrlCanHaveFilesWithColorBlue // true
+
+const secondUrlCanHaveFileWithColorBlue = URL_META.urlChildMayMatch({
+  url: "file:///node_modules/src/",
+  associations,
+  predicate: ({ color }) => color === "blue",
+})
+secondUrlCanHaveFileWithColorBlue // false
+```

package/docs/url_meta/demo/apply_associations.mjs

@@ -0,0 +1,27 @@
+import { URL_META } from "@jsenv/urls"
+
+const associations = {
+  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(
+    URL_META.applyAssociations({ url: urlA, associations }),
+    null,
+    "  ",
+  )}`,
+)
+console.log(
+  `${urlB}: ${JSON.stringify(
+    URL_META.applyAssociations({ url: urlB, associations }),
+    null,
+    "  ",
+  )}`,
+)

package/docs/url_meta/demo/full_match.mjs

@@ -0,0 +1,7 @@
+import { URL_META } from "@jsenv/urls"
+
+const fullMatch = URL_META.applyPatternMatching({
+  pattern: "file:///**/*",
+  url: "file:///Users/directory/file.js",
+})
+console.log(JSON.stringify(fullMatch, null, "  "))

package/docs/url_meta/demo/partial_match.mjs

@@ -0,0 +1,7 @@
+import { URL_META } from "@jsenv/urls"
+
+const partialMatch = URL_META.applyPatternMatching({
+  pattern: "file:///*.js",
+  url: "file:///file.jsx",
+})
+console.log(JSON.stringify(partialMatch, null, "  "))

package/docs/url_meta/demo/resolve_associations.mjs

@@ -0,0 +1,12 @@
+import { URL_META } from "@jsenv/urls"
+
+const associations = URL_META.resolveAssociations(
+  {
+    visible: {
+      "**/*/": true,
+      "**/.git/": false,
+    },
+  },
+  "file:///Users/directory/",
+)
+console.log(JSON.stringify(associations, null, "  "))

package/docs/url_meta/notes.md

@@ -0,0 +1,26 @@
+```js
+// Name of variables in the code below corresponds
+// to the terminology used in the codebase and documentation
+const pattern = "**/*"
+const value = { visible: true }
+const valueMap = {
+  [pattern]: value,
+}
+```
+
+## associations
+
+_associations composition_
+
+```js
+const pattern = "**/*/"
+const key = "visible"
+const value = true
+const meta = { [key]: value }
+const valueMap = {
+  [pattern]: meta,
+}
+const associations = {
+  [key]: valueMap,
+}
+```

package/docs/url_meta/pattern_matching.md

@@ -0,0 +1,71 @@
+# applyPatternMatching
+
+_applyPatternMatching_ is a function returning a _matchResult_ indicating if and how a _pattern_ matches an _url_.
+
+```js
+import { URL_META } from "@jsenv/urls"
+
+const matchResult = URL_META.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_.
+
+### Matching example
+
+```js
+import { URL_META } from "@jsenv/urls"
+
+const fullMatch = URL_META.applyPatternMatching({
+  pattern: "file:///**/*",
+  url: "file:///Users/directory/file.js",
+})
+console.log(JSON.stringify(fullMatch, null, "  "))
+```
+
+```json
+{
+  "matched": true,
+  "patternIndex": 12,
+  "urlIndex": 31,
+  "matchGroups": ["file.js"]
+}
+```
+
+### Partial matching example
+
+```js
+import { applyPatternMatching } from "@jsenv/urlss"
+
+const partialMatch = URL_META.applyPatternMatching({
+  pattern: "file:///*.js",
+  url: "file:///file.jsx",
+})
+console.log(JSON.stringify(partialMatch, null, "  "))
+```
+
+```json
+{
+  "matched": false,
+  "patternIndex": 12,
+  "urlIndex": 15,
+  "matchGroups": ["file"]
+}
+```

package/docs/url_meta/readme.md

@@ -0,0 +1,87 @@
+# url meta
+
+Associate value to urls using pattern matching.
+
+```js
+import { URL_META } from "@jsenv/urls"
+
+// conditionally associates url and values
+const associations = {
+  color: {
+    "file:///*": "black",
+    "file:///*.js": "red",
+  },
+}
+const getUrlColor = (url) => {
+  return URL_META.applyAssociations({ url, associations }).color
+}
+console.log(`file.json color is ${getUrlColor("file:///file.json")}`)
+console.log(`file.js color is ${getUrlColor("file:///file.js")}`)
+```
+
+_Code above logs_
+
+```console
+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        |
+
+Read more at [./pattern_matching.md](./pattern_matching.md)
+
+# associations
+
+_associations_ below translates into: "files are visible except thoose in .git/ directory"
+
+```js
+const associations = {
+  visible: {
+    "**/*/": true,
+    "**/.git/": false,
+  },
+}
+```
+
+_associations_ allows to group patterns per property which are easy to read and compose.
+All keys in _associations_ must be absolute urls, this can be done with [resolveAssociations](#resolveAssociations).
+
+# resolveAssociations
+
+_resolveAssociations_ is a function resolving _associations_ keys that may contain relative urls against an _url_.
+
+```js
+import { URL_META } from "@jsenv/urls"
+
+const associations = URL_META.resolveAssociations(
+  {
+    visible: {
+      "**/*/": true,
+      "**/.git/": false,
+    },
+  },
+  "file:///Users/directory/",
+)
+console.log(JSON.stringify(associations, null, "  "))
+```
+
+```json
+{
+  "visible": {
+    "file:///Users/directory/**/*/": true,
+    "file:///Users/directory/**/.git/": false
+  }
+}
+```

package/main.js

@@ -0,0 +1,27 @@
+export { DataUrl } from "./src/data_url.js"
+export { generateInlineContentUrl } from "./src/inline_content_url_generator.js"
+export {
+  stringifyUrlTrace,
+  stringifyUrlSite,
+  humanizeUrl,
+  showSourceLocation,
+} from "./src/url_trace.js"
+export {
+  asUrlWithoutSearch,
+  isValidUrl,
+  normalizeUrl,
+  injectQueryParamsIntoSpecifier,
+  injectQueryParams,
+  setUrlExtension,
+  setUrlFilename,
+  ensurePathnameTrailingSlash,
+  asUrlUntilPathname,
+} from "./src/url_utils.js"
+export {
+  startsWithWindowsDriveLetter,
+  windowsFilePathToUrl,
+  replaceBackSlashesWithSlashes,
+} from "./src/windows_file_path_utils.js"
+export { getCallerPosition } from "./src/caller_position.js"
+
+export { URL_META } from "./src/meta/url_meta.js"

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@jsenv/urls",
+  "version": "1.0.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jsenv/jsenv-core",
+    "directory": "packages/urls"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./main.js"
+    },
+    "./*": "./*"
+  },
+  "scripts": {
+    "test": "node --conditions=development ./test.mjs"
+  },
+  "dependencies": {
+    "@jsenv/filesystem": "3.1.0",
+    "@jsenv/log": "1.6.3"
+  }
+}

package/src/caller_position.js

@@ -0,0 +1,20 @@
+import { isFileSystemPath, fileSystemPathToUrl } from "@jsenv/filesystem"
+
+export const getCallerPosition = () => {
+  const { prepareStackTrace } = Error
+  Error.prepareStackTrace = (error, stack) => {
+    Error.prepareStackTrace = prepareStackTrace
+    return stack
+  }
+  const { stack } = new Error()
+  const callerCallsite = stack[2]
+  const fileName = callerCallsite.getFileName()
+  return {
+    url:
+      fileName && isFileSystemPath(fileName)
+        ? fileSystemPathToUrl(fileName)
+        : fileName,
+    line: callerCallsite.getLineNumber(),
+    column: callerCallsite.getColumnNumber(),
+  }
+}

package/src/data_url.js

@@ -0,0 +1,50 @@
+/*
+ * data:[<mediatype>][;base64],<data>
+ * https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs#syntax
+ */
+
+/* eslint-env browser, node */
+
+export const DataUrl = {
+  parse: (string) => {
+    const afterDataProtocol = string.slice("data:".length)
+    const commaIndex = afterDataProtocol.indexOf(",")
+    const beforeComma = afterDataProtocol.slice(0, commaIndex)
+
+    let contentType
+    let base64Flag
+    if (beforeComma.endsWith(`;base64`)) {
+      contentType = beforeComma.slice(0, -`;base64`.length)
+      base64Flag = true
+    } else {
+      contentType = beforeComma
+      base64Flag = false
+    }
+
+    contentType =
+      contentType === "" ? "text/plain;charset=US-ASCII" : contentType
+    const afterComma = afterDataProtocol.slice(commaIndex + 1)
+    return {
+      contentType,
+      base64Flag,
+      data: afterComma,
+    }
+  },
+
+  stringify: ({ contentType, base64Flag = true, data }) => {
+    if (!contentType || contentType === "text/plain;charset=US-ASCII") {
+      // can be a buffer or a string, hence check on data.length instead of !data or data === ''
+      if (data.length === 0) {
+        return `data:,`
+      }
+      if (base64Flag) {
+        return `data:;base64,${data}`
+      }
+      return `data:,${data}`
+    }
+    if (base64Flag) {
+      return `data:${contentType};base64,${data}`
+    }
+    return `data:${contentType},${data}`
+  },
+}

package/src/inline_content_url_generator.js

@@ -0,0 +1,21 @@
+import { urlToFilename } from "@jsenv/filesystem"
+
+export const generateInlineContentUrl = ({
+  url,
+  extension,
+  line,
+  column,
+  lineEnd,
+  columnEnd,
+}) => {
+  const generatedName =
+    line === lineEnd
+      ? `L${line}C${column}-L${lineEnd}C${columnEnd}`
+      : `L${line}-L${lineEnd}`
+  const filenameRaw = urlToFilename(url)
+  const filename = `${filenameRaw}@${generatedName}${extension}`
+  // ideally we should keep query params from url
+  // maybe we could use a custom scheme like "inline:"
+  const inlineContentUrl = new URL(filename, url).href
+  return inlineContentUrl
+}

package/src/meta/aliases.js

@@ -0,0 +1,28 @@
+import { applyPatternMatching } from "./pattern_matching.js"
+
+export const applyAliases = ({ url, aliases }) => {
+  let aliasFullMatchResult
+  const aliasMatchingKey = Object.keys(aliases).find((key) => {
+    const aliasMatchResult = applyPatternMatching({
+      pattern: key,
+      url,
+    })
+    if (aliasMatchResult.matched) {
+      aliasFullMatchResult = aliasMatchResult
+      return true
+    }
+    return false
+  })
+  if (!aliasMatchingKey) {
+    return url
+  }
+  const { matchGroups } = aliasFullMatchResult
+  const alias = aliases[aliasMatchingKey]
+  const parts = alias.split("*")
+  const newUrl = parts.reduce((previous, value, index) => {
+    return `${previous}${value}${
+      index === parts.length - 1 ? "" : matchGroups[index]
+    }`
+  }, "")
+  return newUrl
+}

package/src/meta/as_flat_associations.js

@@ -0,0 +1,28 @@
+import { isPlainObject } from "./assertions.js"
+
+export const asFlatAssociations = (associations) => {
+  if (!isPlainObject(associations)) {
+    throw new TypeError(
+      `associations must be a plain object, got ${associations}`,
+    )
+  }
+  const flatAssociations = {}
+  Object.keys(associations).forEach((key) => {
+    const valueMap = associations[key]
+    if (!isPlainObject(valueMap)) {
+      throw new TypeError(
+        `all associations value must be objects, found "${key}": ${valueMap}`,
+      )
+    }
+    Object.keys(valueMap).forEach((pattern) => {
+      const value = valueMap[pattern]
+      const previousValue = flatAssociations[pattern]
+      flatAssociations[pattern] = previousValue
+        ? { ...previousValue, [key]: value }
+        : {
+            [key]: value,
+          }
+    })
+  })
+  return flatAssociations
+}

package/src/meta/assertions.js

@@ -0,0 +1,57 @@
+export const assertSpecifierMetaMap = (value, checkComposition = true) => {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`specifierMetaMap must be a plain object, got ${value}`)
+  }
+  if (checkComposition) {
+    const plainObject = value
+    Object.keys(plainObject).forEach((key) => {
+      assertUrlLike(key, "specifierMetaMap key")
+      const value = plainObject[key]
+      if (value !== null && !isPlainObject(value)) {
+        throw new TypeError(
+          `specifierMetaMap value must be a plain object or null, got ${value} under key ${key}`,
+        )
+      }
+    })
+  }
+}
+
+export const assertUrlLike = (value, name = "url") => {
+  if (typeof value !== "string") {
+    throw new TypeError(`${name} must be a url string, got ${value}`)
+  }
+  if (isWindowsPathnameSpecifier(value)) {
+    throw new TypeError(
+      `${name} must be a url but looks like a windows pathname, got ${value}`,
+    )
+  }
+  if (!hasScheme(value)) {
+    throw new TypeError(
+      `${name} must be a url and no scheme found, got ${value}`,
+    )
+  }
+}
+
+export const isPlainObject = (value) => {
+  if (value === null) {
+    return false
+  }
+  if (typeof value === "object") {
+    if (Array.isArray(value)) {
+      return false
+    }
+    return true
+  }
+  return false
+}
+
+const isWindowsPathnameSpecifier = (specifier) => {
+  const firstChar = specifier[0]
+  if (!/[a-zA-Z]/.test(firstChar)) return false
+  const secondChar = specifier[1]
+  if (secondChar !== ":") return false
+  const thirdChar = specifier[2]
+  return thirdChar === "/" || thirdChar === "\\"
+}
+
+const hasScheme = (specifier) => /^[a-zA-Z]+:/.test(specifier)

package/src/meta/associations.js

@@ -0,0 +1,25 @@
+import { assertUrlLike, isPlainObject } from "./assertions.js"
+import { asFlatAssociations } from "./as_flat_associations.js"
+import { applyPatternMatching } from "./pattern_matching.js"
+
+export const applyAssociations = ({ url, associations }) => {
+  assertUrlLike(url)
+  const flatAssociations = asFlatAssociations(associations)
+  return Object.keys(flatAssociations).reduce((previousValue, pattern) => {
+    const { matched } = applyPatternMatching({
+      pattern,
+      url,
+    })
+    if (matched) {
+      const value = flatAssociations[pattern]
+      if (isPlainObject(previousValue) && isPlainObject(value)) {
+        return {
+          ...previousValue,
+          ...value,
+        }
+      }
+      return value
+    }
+    return previousValue
+  }, {})
+}