@najemi-software/typed-scss-modules 10.3.0

package/dist/lib/prettier/index.js

@@ -0,0 +1,44 @@
+import { format, resolveConfig } from "prettier";
+import { alerts } from "../core/alerts.js";
+import { canResolvePrettier } from "./can-resolve.js";
+const isPrettier = (t) => !!t &&
+    typeof t === "object" &&
+    t !== null &&
+    "format" in t &&
+    typeof t.format === "function" &&
+    "resolveConfig" in t &&
+    typeof t.resolveConfig === "function";
+/**
+ * Try to load prettier and config from project to format input,
+ * fall back to input if prettier is not found or failed
+ *
+ * @param {file} file
+ * @param {string} input
+ */
+export const attemptPrettier = async (file, input) => {
+    if (!canResolvePrettier()) {
+        return input;
+    }
+    const prettier = await import("prettier");
+    if (!isPrettier(prettier)) {
+        // doesn't look like prettier
+        return input;
+    }
+    try {
+        const config = await prettier
+            .resolveConfig(file, {
+            editorconfig: true,
+        })
+            .catch(() => {
+            /* default */
+        });
+        // try to return formatted output
+        return prettier.format(input, { ...config, parser: "typescript" });
+    }
+    catch (error) {
+        // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+        alerts.notice(`Tried using prettier, but failed with error: ${error}`);
+    }
+    // failed to format
+    return input;
+};

package/dist/lib/sass/file-to-class-names.d.ts

@@ -0,0 +1,25 @@
+import { type Options } from "sass";
+import { type Implementations } from "../implementations/index.js";
+import { type Aliases, type SASSImporter, type SASSImporterOptions, type SyncMode } from "./importer.js";
+export type { Aliases };
+export type ClassName = string;
+declare const transformersMap: {
+    readonly camel: (className: ClassName) => string;
+    readonly dashes: (className: ClassName) => string;
+    readonly kebab: (className: ClassName) => string;
+    readonly none: (className: ClassName) => string;
+    readonly param: (className: ClassName) => string;
+    readonly snake: (className: ClassName) => string;
+};
+type NameFormatWithTransformer = keyof typeof transformersMap;
+export declare const NAME_FORMATS: readonly [...("camel" | "dashes" | "kebab" | "none" | "param" | "snake")[], "all"];
+export type NameFormat = (typeof NAME_FORMATS)[number];
+export type InternalSassOptions = Pick<Options<SyncMode>, "style" | "loadPaths" | "silenceDeprecations">;
+export interface SASSOptions extends SASSImporterOptions, InternalSassOptions {
+    nameFormat?: string | string[];
+    implementation: Implementations;
+    async?: boolean;
+    importers?: SASSImporter<SyncMode>[];
+}
+export declare const nameFormatDefault: NameFormatWithTransformer;
+export declare const fileToClassNames: (file: string, { style, loadPaths, silenceDeprecations, nameFormat: rawNameFormat, implementation, aliases, aliasPrefixes, importers, async, }?: SASSOptions) => Promise<string[]>;

package/dist/lib/sass/file-to-class-names.js

@@ -0,0 +1,55 @@
+import { camelCase, camelCaseTransformMerge, paramCase, snakeCase, } from "change-case";
+import {} from "sass";
+import { getAsyncCompiler, getImplementation, getSyncCompiler, } from "../implementations/index.js";
+import { customImporters, } from "./importer.js";
+import { sourceToClassNames } from "./source-to-class-names.js";
+const transformersMap = {
+    camel: (className) => camelCase(className, { transform: camelCaseTransformMerge }),
+    dashes: (className) => /-/.test(className) ? camelCase(className) : className,
+    kebab: (className) => transformersMap.param(className),
+    none: (className) => className,
+    param: (className) => paramCase(className),
+    snake: (className) => snakeCase(className),
+};
+const NAME_FORMATS_WITH_TRANSFORMER = Object.keys(transformersMap);
+export const NAME_FORMATS = [...NAME_FORMATS_WITH_TRANSFORMER, "all"];
+export const nameFormatDefault = "camel";
+export const fileToClassNames = async (file, { style = "expanded", loadPaths = [], silenceDeprecations = [], nameFormat: rawNameFormat, implementation, aliases, aliasPrefixes, importers = [], async = false, } = {}) => {
+    const root = await getImplementation(implementation);
+    const nameFormat = (typeof rawNameFormat === "string" ? [rawNameFormat] : rawNameFormat);
+    const nameFormats = nameFormat
+        ? nameFormat.includes("all")
+            ? NAME_FORMATS_WITH_TRANSFORMER
+            : nameFormat
+        : [nameFormatDefault];
+    const result = !async
+        ? getSyncCompiler({ implementation, root }).compile(file, {
+            style,
+            silenceDeprecations, // Suppress specified deprecations
+            importers: customImporters({
+                aliases,
+                aliasPrefixes,
+                importers,
+            }),
+            loadPaths: loadPaths,
+        })
+        : await (await getAsyncCompiler({ implementation, root })).compileAsync(file, {
+            style,
+            silenceDeprecations, // Suppress specified deprecations
+            importers: customImporters({
+                aliases,
+                aliasPrefixes,
+                importers,
+            }),
+            loadPaths: loadPaths,
+        });
+    const classNames = await sourceToClassNames(result.css, file);
+    const transformers = nameFormats.map((item) => transformersMap[item]);
+    const transformedClassNames = new Set([]);
+    classNames.forEach((className) => {
+        transformers.forEach((transformer) => {
+            transformedClassNames.add(transformer(className));
+        });
+    });
+    return Array.from(transformedClassNames).sort((a, b) => a.localeCompare(b));
+};

package/dist/lib/sass/importer.d.ts

@@ -0,0 +1,29 @@
+import type { FileImporter, Importer as SassImporter } from "sass";
+export type SyncMode = "sync" | "async";
+type Importer<TSync extends SyncMode = "sync"> = SassImporter<TSync> | FileImporter<TSync>;
+type AsyncImporter = Importer<"async">;
+export type { AsyncImporter as SASSAsyncImporter, Importer as SASSImporter };
+export interface Aliases {
+    [index: string]: string;
+}
+interface AliasImporterOptions {
+    aliases: Aliases;
+    aliasPrefixes: Aliases;
+}
+/**
+ * Construct a SASS importer to create aliases for imports.
+ */
+export declare const aliasResolver: ({ aliases, aliasPrefixes }: AliasImporterOptions) => (url: string) => string | null;
+export declare const aliasImporter: <TSync extends SyncMode = "sync">({ aliases, aliasPrefixes, }: AliasImporterOptions) => FileImporter<TSync>;
+export interface SASSImporterOptions {
+    aliases?: Aliases;
+    aliasPrefixes?: Aliases;
+    importers?: Importer[];
+}
+/**
+ * Construct custom SASS importers based on options.
+ *
+ *  - Given aliases and alias prefix options, add a custom alias importer.
+ *  - Given custom SASS importer(s), append to the list of importers.
+ */
+export declare const customImporters: <TSync extends SyncMode = "sync">({ aliases, aliasPrefixes, importers, }: SASSImporterOptions) => Importer<TSync>[];

package/dist/lib/sass/importer.js

@@ -0,0 +1,37 @@
+import { pathToFileURL } from "url";
+/**
+ * Construct a SASS importer to create aliases for imports.
+ */
+export const aliasResolver = ({ aliases, aliasPrefixes }) => (url) => {
+    if (url in aliases) {
+        return aliases[url];
+    }
+    const prefixMatch = Object.keys(aliasPrefixes).find((prefix) => url.startsWith(prefix));
+    if (prefixMatch) {
+        return aliasPrefixes[prefixMatch] + url.substr(prefixMatch.length);
+    }
+    return null;
+};
+export const aliasImporter = ({ aliases, aliasPrefixes, }) => {
+    const resolveFileUrl = aliasResolver({ aliases, aliasPrefixes });
+    return {
+        findFileUrl(url) {
+            const alias = resolveFileUrl(url);
+            if (!alias)
+                return null;
+            return pathToFileURL(alias);
+        },
+    };
+};
+/**
+ * Construct custom SASS importers based on options.
+ *
+ *  - Given aliases and alias prefix options, add a custom alias importer.
+ *  - Given custom SASS importer(s), append to the list of importers.
+ */
+export const customImporters = ({ aliases = {}, aliasPrefixes = {}, importers = [], }) => {
+    const bundled = [
+        aliasImporter({ aliases, aliasPrefixes }),
+    ];
+    return bundled.concat(importers);
+};

package/dist/lib/sass/index.d.ts

@@ -0,0 +1 @@
+export { NAME_FORMATS, fileToClassNames, nameFormatDefault, type Aliases, type SASSOptions, } from "./file-to-class-names.js";

package/dist/lib/sass/index.js

@@ -0,0 +1 @@
+export { NAME_FORMATS, fileToClassNames, nameFormatDefault, } from "./file-to-class-names.js";

package/dist/lib/sass/source-to-class-names.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Converts a CSS source string to a list of exports (class names, keyframes, etc.)
+ */
+export declare const sourceToClassNames: (source: {
+    toString(): string;
+}, file: string) => Promise<string[]>;

package/dist/lib/sass/source-to-class-names.js

@@ -0,0 +1,16 @@
+import postcss from "postcss";
+import PostcssModulesPlugin from "postcss-modules";
+/**
+ * Converts a CSS source string to a list of exports (class names, keyframes, etc.)
+ */
+export const sourceToClassNames = async (source, file) => {
+    let result = {};
+    await postcss([
+        PostcssModulesPlugin({
+            getJSON: (_, json) => {
+                result = json;
+            },
+        }),
+    ]).process(source, { from: file });
+    return Object.keys(result);
+};

package/dist/lib/typescript/class-names-to-type-definition.d.ts

@@ -0,0 +1,20 @@
+import type { ClassName } from "lib/sass/file-to-class-names.js";
+export type ExportType = "named" | "default";
+export declare const EXPORT_TYPES: ExportType[];
+export type QuoteType = "single" | "double";
+export declare const QUOTE_TYPES: QuoteType[];
+export interface TypeDefinitionOptions {
+    banner: string;
+    classNames: ClassName[];
+    file: string;
+    exportType: ExportType;
+    exportTypeName?: string;
+    exportTypeInterface?: string;
+    quoteType?: QuoteType;
+}
+export declare const exportTypeDefault: ExportType;
+export declare const exportTypeNameDefault: string;
+export declare const exportTypeInterfaceDefault: string;
+export declare const quoteTypeDefault: QuoteType;
+export declare const bannerTypeDefault: string;
+export declare const classNamesToTypeDefinitions: (options: TypeDefinitionOptions) => Promise<string | null>;

package/dist/lib/typescript/class-names-to-type-definition.js

@@ -0,0 +1,64 @@
+import os from "os";
+import reserved from "reserved-words";
+import { alerts } from "../core/alerts.js";
+export const EXPORT_TYPES = ["named", "default"];
+export const QUOTE_TYPES = ["single", "double"];
+export const exportTypeDefault = "named";
+export const exportTypeNameDefault = "ClassNames";
+export const exportTypeInterfaceDefault = "Styles";
+export const quoteTypeDefault = "single";
+export const bannerTypeDefault = "";
+const classNameToNamedTypeDefinition = (className) => `export declare const ${className}: string;`;
+const classNameToType = (className, quoteType) => {
+    const quote = quoteType === "single" ? "'" : '"';
+    return `  ${quote}${className}${quote}: string;`;
+};
+const isReservedKeyword = (className) => reserved.check(className, "es5", true) ||
+    reserved.check(className, "es6", true);
+const isValidName = (className) => {
+    if (isReservedKeyword(className)) {
+        alerts.warn(`[SKIPPING] '${className}' is a reserved keyword (consider renaming or using --exportType default).`);
+        return false;
+    }
+    else if (/-/.test(className)) {
+        alerts.warn(`[SKIPPING] '${className}' contains dashes (consider using 'camelCase' or 'dashes' for --nameFormat or using --exportType default).`);
+        return false;
+    }
+    return true;
+};
+export const classNamesToTypeDefinitions = async (options) => {
+    if (options.classNames.length) {
+        const lines = [];
+        const { exportTypeName: ClassNames = exportTypeNameDefault, exportTypeInterface: Styles = exportTypeInterfaceDefault, } = options;
+        switch (options.exportType) {
+            case "default":
+                if (options.banner)
+                    lines.push(options.banner);
+                lines.push(`export type ${Styles} = {`);
+                lines.push(...options.classNames.map((className) => classNameToType(className, options.quoteType || quoteTypeDefault)));
+                lines.push(`};${os.EOL}`);
+                lines.push(`export type ${ClassNames} = keyof ${Styles};${os.EOL}`);
+                lines.push(`declare const styles: ${Styles};${os.EOL}`);
+                lines.push(`export default styles;`);
+                break;
+            case "named":
+                if (options.banner)
+                    lines.push(options.banner);
+                lines.push(...options.classNames
+                    .filter(isValidName)
+                    .map(classNameToNamedTypeDefinition));
+                break;
+        }
+        if (lines.length) {
+            const typeDefinition = lines.join(`${os.EOL}`) + `${os.EOL}`;
+            // return await attemptPrettier(options.file, typeDefinition); // ignore prettier (slows down)
+            return typeDefinition;
+        }
+        else {
+            return null;
+        }
+    }
+    else {
+        return null;
+    }
+};

package/dist/lib/typescript/get-type-definition-path.d.ts

@@ -0,0 +1,8 @@
+import type { ConfigOptions } from "../core/types.js";
+/**
+ * Given a file path to a SCSS file, generate the corresponding type definition
+ * file path.
+ *
+ * @param file the SCSS file path
+ */
+export declare const getTypeDefinitionPath: (file: string, options: ConfigOptions) => string;

package/dist/lib/typescript/get-type-definition-path.js

@@ -0,0 +1,25 @@
+import path from "path";
+const CURRENT_WORKING_DIRECTORY = process.cwd();
+/**
+ * Given a file path to a SCSS file, generate the corresponding type definition
+ * file path.
+ *
+ * @param file the SCSS file path
+ */
+export const getTypeDefinitionPath = (file, options) => {
+    let resolvedPath = file;
+    if (options.outputFolder) {
+        const relativePath = path.relative(CURRENT_WORKING_DIRECTORY, file);
+        resolvedPath = path.resolve(CURRENT_WORKING_DIRECTORY, options.outputFolder, relativePath);
+    }
+    if (options.allowArbitraryExtensions) {
+        const resolvedDirname = path.dirname(resolvedPath);
+        // Note: `ext` includes a leading period (e.g. '.scss')
+        const { name, ext } = path.parse(resolvedPath);
+        // @see https://www.typescriptlang.org/tsconfig/#allowArbitraryExtensions
+        return path.join(resolvedDirname, `${name}.d${ext}.ts`);
+    }
+    else {
+        return `${resolvedPath}.d.ts`;
+    }
+};

package/dist/lib/typescript/index.d.ts

@@ -0,0 +1,3 @@
+export { LOG_LEVELS, logLevelDefault, type LogLevel } from "../core/alerts.js";
+export { EXPORT_TYPES, QUOTE_TYPES, bannerTypeDefault, classNamesToTypeDefinitions, exportTypeDefault, exportTypeInterfaceDefault, exportTypeNameDefault, quoteTypeDefault, type ExportType, type QuoteType, } from "./class-names-to-type-definition.js";
+export { getTypeDefinitionPath } from "./get-type-definition-path.js";

package/dist/lib/typescript/index.js

@@ -0,0 +1,3 @@
+export { LOG_LEVELS, logLevelDefault } from "../core/alerts.js";
+export { EXPORT_TYPES, QUOTE_TYPES, bannerTypeDefault, classNamesToTypeDefinitions, exportTypeDefault, exportTypeInterfaceDefault, exportTypeNameDefault, quoteTypeDefault, } from "./class-names-to-type-definition.js";
+export { getTypeDefinitionPath } from "./get-type-definition-path.js";

package/package.json

@@ -0,0 +1,120 @@
+{
+  "name": "@najemi-software/typed-scss-modules",
+  "version": "10.3.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "TypeScript type definition generator for SCSS CSS Modules",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/lib/index.d.ts",
+      "import": "./dist/lib/index.js",
+      "require": "./dist/lib/index.js",
+      "default": "./dist/lib/index.js"
+    }
+  },
+  "main": "dist/lib/index.js",
+  "types": "dist/lib/index.d.ts",
+  "author": "am0wa <am0wa.it@gmail.com>",
+  "contributors": [
+    {
+      "name": "Spencer Miskoviak",
+      "email": "smiskoviak@gmail.com"
+    }
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.19",
+    "npm": ">=10.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Najemi-Software/typed-scss-modules.git"
+  },
+  "homepage": "https://github.com/Najemi-Software/typed-scss-modules#readme",
+  "keywords": [
+    "scss",
+    "css modules",
+    "cli",
+    "typescript",
+    "type generator",
+    "scss modules"
+  ],
+  "files": [
+    "dist/lib"
+  ],
+  "bin": {
+    "typed-scss-modules": "./dist/lib/cli.js"
+  },
+  "scripts": {
+    "test": "jest --silent",
+    "test:watch": "jest --watch",
+    "typed-scss-modules": "node ./dist/lib/cli.js",
+    "clean": "rm -rf ./dist",
+    "build": "npm run clean && tsc && chmod +x dist/lib/cli.js",
+    "check:types": "tsc --noEmit",
+    "check:formatting": "prettier --check '**/*.{js,json,css,md,scss,tsx,ts}'",
+    "check:linting": "eslint .",
+    "commit": "commit",
+    "prepare": "npm run build && husky",
+    "prepublishOnly": "[ \"$CI\" = \"true\" ] || (npm run build && npm test)",
+    "semantic-release": "semantic-release"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.2.0",
+    "@commitlint/config-conventional": "^20.2.0",
+    "@commitlint/prompt-cli": "^20.2.0",
+    "@swc/core": "^1.15.8",
+    "@swc/jest": "^0.2.39",
+    "@tsjam/eslint-config-recommended": "^0.2.4",
+    "@tsjam/swc-jest-config-recommended": "^0.1.4",
+    "@types/node": "^17.0.18",
+    "@types/reserved-words": "^0.1.0",
+    "@types/yargs": "^17.0.35",
+    "eslint": "^9.34.0",
+    "eslint-plugin-jest": "^29.11.0",
+    "husky": "^9.1.7",
+    "jest": "^30.2.0",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.6.2",
+    "prettier-plugin-organize-imports": "^3.2.4",
+    "sass": "^1.97.1",
+    "sass-embedded": "^1.97.1",
+    "semantic-release": "^25.0.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "sass": "^1.97.1",
+    "sass-embedded": "^1.97.1"
+  },
+  "peerDependenciesMeta": {
+    "sass": {
+      "optional": true
+    },
+    "sass-embedded": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "bundle-require": "^5.1.0",
+    "chalk": "4.1.2",
+    "change-case": "^4.1.2",
+    "chokidar": "^3.6.0",
+    "esbuild": "^0.27.2",
+    "glob": "^13.0.0",
+    "joycon": "^3.1.1",
+    "postcss": "^8.4.49",
+    "postcss-modules": "^6.0.1",
+    "reserved-words": "^0.1.2",
+    "slash": "^3.0.0",
+    "yargs": "^17.7.2"
+  },
+  "lint-staged": {
+    "*.{js,json,css,md,scss,tsx,ts}": [
+      "prettier --write"
+    ]
+  }
+}