# @joneff/sass-import-resolver

> Resolves the path of sass imports, following a heavily opinionated and probably very shady algorithm

Latest version **1.0.0** (published 2021-07-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install @joneff/sass-import-resolver
pnpm add @joneff/sass-import-resolver
yarn add @joneff/sass-import-resolver
bun add @joneff/sass-import-resolver
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2021-07-29 |
| First published | 2019-09-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 10.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Ivan Zhekov |
| Maintainers | joneff |
| Keywords | sass, import, resolver |

## Links

- npm: https://www.npmjs.com/package/@joneff/sass-import-resolver
- Repository: https://github.com/joneff/sass-import-resolver
- Homepage: https://github.com/joneff/sass-import-resolver#readme
- Issues: https://github.com/joneff/sass-import-resolver/issues
- npm.io page: https://npm.io/package/@joneff/sass-import-resolver

## Dependencies (1)

- [lodash.merge](https://npm.io/package/lodash.merge.md) ^4.6.2

## Alternatives

- [base64url](https://npm.io/package/base64url.md) — 6.1M weekly downloads
- [get-installed-path](https://npm.io/package/get-installed-path.md) — 502.9K weekly downloads
- [@d3fc/d3fc-shape](https://npm.io/package/@d3fc/d3fc-shape.md) — 16.2K weekly downloads
- [localizer](https://npm.io/package/localizer.md) — 226 weekly downloads
- [tg-resolve](https://npm.io/package/tg-resolve.md) — 176 weekly downloads

## Recent versions

- 1.0.0 (latest) — 2021-07-29
- 0.4.0 — 2021-07-28
- 0.3.1 — 2020-06-01
- 0.3.0 — 2020-06-01
- 0.2.1 — 2019-09-29
- 0.2.0 — 2019-09-29
- 0.1.1 — 2019-09-28

## README

# sass-import-resolver

[sass-import-resolver] resolves the path of sass imports, following a heavily opinionated and probably very shady algorithm, which I will get to in a bit.

## Purpose

The purpose of the package is to be used for [sass importers] or similar scripts. The [API](#API) has similar signature to a sass importer.

## Installation

```shell
npm install @joneff/sass-import-resolver --save-dev
```

## Basic Usage

> It's probably not a good idea to use in any production code, without rigorous testing. Usage may feel a bit like a [Kübler-Ross] [grief cycle] -- denial, anger, barganing, depression, acceptance -- but it's the only sane solution I was able to come up with.
>
> -- me

Something like this will yield results:

```javascript
const resolver = require('@joneff/sass-import-resolver');

// assuming @import "../some/dependency.scss" in ./my/overly/nested/framework.scss
const file = ...;
const options = ...;

const result = resolver.resolve({ file, ...options });

console.log(result);
// if the file exists => ./my/overly/some/dependecy.scss
// if not => ../some/dependency.scss
```

## API

The api has only two methods with both using the same params.

### resolve()

* Signature: `function resolve( options: { file: String, prev?: String, includePaths?: Array<String>, nodeModules?: String } ) : String`

Just a facade -- passes everything down to `_resove` and waits for results.

### _resolve()

* Signature: `function _resolve( options: { file: String, prev?: String, includePaths?: Array<String>, nodeModules?: String } ) : Array<String>`

Does the actual work, collects **unique** matches and returns them.

### options

* `options.file` -- Path to a file
* `options.prev` (Optional) -- Path to file (or dir) to be used for resolving `url`. Ideally, it should not be empty and should be the previously resolved path.
* `options.includePaths` (Optional) -- An array of paths that the script can look in when attempting to resolve `@import` declarations. When resolving node_module (`~`), absolute (`/`) or parent (`../`) imports, this has no effect.
* `options.nodeModules` (Optional) -- Location of `node_modules` when resolving. Defaults to `./node_modules`.

## Heavily Opinionated and Probably Very Shady Algorithm

The algorithm is based on [Sass `@import` documentation], and should work as follows, assuming atleast `options.file` param is passed:

1) if `file` starts with `http://`, `https://`, `//`, `\\\\` or `url(`, it's not proccessed at all and returned as is;
2) if `prev` is file, set `cwd` to the directory that file is in;
3) if `prev` is directory, set `cwd` to that directory;
4) if `prev` is not passed, set `cwd` to `proccess.cwd()`;
5) if `includePaths` is not passed, assume it's an empty array;
6) if `file` is absolute path, clear `cwd` and `includePaths`;
7) if `file` starts with `~`, assume node_modules import, set `cwd` to `node_modules` and clear `includePaths`;
8) if `file` starts with `.`, clear `includePaths`;
9) assuming there are any `includePaths` left, unique them with `cwd` and loop them:
    1) if the file portion of `file` has `.css`, `.scss`, or `.sass` extension, resolve tha path and return it;
    2) if the file portion `file` starts with `_`, resolve and return the following 7 variants in that order:
        1) `_file.css`
        2) `_file.scss`
        3) `_file.sass`
        4) `file/index.scss` (that's an exception from sass @import)
        5) `file/index.sass`  (that's an exception from sass @import)
        6) `file/_index.scss`
        7) `file/_index.sass`
    3) resolve and return the following 9 variants in that order:
        1) `file.css`
        2) `file.scss`
        3) `file.sass`
        4) `_file.scss`
        5) `_file.sass`
        6) `file/index.scss` (that's an exception from sass @import)
        7) `file/index.sass`  (that's an exception from sass @import)
        8) `file/_index.scss`
        9) `file/_index.sass`
10) assuming there is an array of matches, loop over:
    1) return the resolved path of the first file that exists on the file system
    2) otherwise return the original `file`

Surely, the algorithm can be extended in various directions like scraping the `package.json` of resolved modules and looking for entry points, which is not a bad idea at all. However, if you are a sass package creator and you rely on such custom logic, things will not go well for consumers of said packages.

## Contributing?

Sure.

[sass-import-resolver]: https://github.com/joneff/sass-import-resolver
[sass importers]: https://github.com/sass/node-sass#importer--v200---experimental
[Kübler-Ross]: https://en.wikipedia.org/wiki/Elisabeth_K%C3%BCbler-Ross
[grief cycle]: https://en.wikipedia.org/wiki/K%C3%BCbler-Ross_model
[Sass `@import` documentation]: https://sass-lang.com/documentation/at-rules/import

---
_Source: https://npm.io/package/@joneff/sass-import-resolver · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._