@uzum-tech/design-tokens-resolver 0.0.0-stage → 1.0.0

package/lib/index.mjs

@@ -0,0 +1,726 @@
+// src/constants/design.constants.ts
+var designPaths = {
+  release: "/dynamic/design/admin/token-releases/details",
+  releasePayload: "/dynamic/design/admin/token-release-payloads/details",
+  channel: "/dynamic/design/admin/token-channels/details"
+};
+var engineBaseUrls = {
+  local: "http://localhost:3003/api/v1",
+  development: "https://esb-data-engine-int-dev.kapitalbank.uz/api/v1",
+  production: "https://data-engine-int.kapitalbank.uz/api/v1"
+};
+var designConfigFiles = [
+  "design-tokens.config.mjs",
+  "design-tokens.config.js",
+  "design-tokens.config.cjs",
+  "design-tokens.config.json"
+];
+var JSON_CONFIG_SUFFIX = ".json";
+var designDefaults = {
+  env: "production",
+  requestTimeoutInMs: 3e4,
+  retryCount: 2,
+  retryDelayInMs: 500,
+  fileName: "tokens.json",
+  lockFileName: "tokens.lock.json",
+  authEnvHint: "DESIGN_TOKENS_API_KEY \u043B\u0438\u0431\u043E DESIGN_TOKENS_USERNAME \u0438 DESIGN_TOKENS_PASSWORD"
+};
+var JSON_INDENT = 2;
+var LINE_BREAK = "\n";
+var HASH_ALGORITHM = "sha256";
+var HASH_ENCODING = "hex";
+
+// src/types/error.types.ts
+var ErrorTypes;
+((ErrorTypes2) => {
+  let Code;
+  ((Code2) => {
+    Code2["CONFIG_INVALID"] = "CONFIG_INVALID";
+    Code2["REQUEST_FAILED"] = "REQUEST_FAILED";
+    Code2["RELEASE_NOT_FOUND"] = "RELEASE_NOT_FOUND";
+    Code2["CHANNEL_EMPTY"] = "CHANNEL_EMPTY";
+    Code2["INTEGRITY_MISMATCH"] = "INTEGRITY_MISMATCH";
+    Code2["WRITE_FAILED"] = "WRITE_FAILED";
+  })(Code = ErrorTypes2.Code || (ErrorTypes2.Code = {}));
+})(ErrorTypes || (ErrorTypes = {}));
+
+// src/constants/regular-expressions.constants.ts
+var regularExpressions = {
+  trailingSlashes: /\/+$/,
+  leadingSlashes: /^\/+/,
+  kebabSegment: /-([a-z])/g,
+  dtcgAlias: /^\{(.+)\}$/
+};
+
+// src/utils/url.utils.ts
+var UrlUtils = class {
+  static join(...parts) {
+    const [head, ...rest] = parts.filter(Boolean);
+    const tail = rest.map((part) => part.replace(regularExpressions.leadingSlashes, "").replace(regularExpressions.trailingSlashes, "")).filter(Boolean);
+    const base = (head ?? "").replace(regularExpressions.trailingSlashes, "");
+    return [base, ...tail].join("/");
+  }
+  static toQuery(params) {
+    const search = new URLSearchParams();
+    for (const key of Object.keys(params)) {
+      const value = params[key];
+      if (!value) continue;
+      search.set(key, String(value));
+    }
+    const query = search.toString();
+    return query ? `?${query}` : "";
+  }
+};
+
+// src/constants/http.constants.ts
+var httpHeaders = {
+  authorization: "authorization",
+  apiKey: "x-api-key"
+};
+
+// src/errors/resolver.error.ts
+var ResolverError = class _ResolverError extends Error {
+  code;
+  statusCode;
+  body;
+  constructor(message, options) {
+    super(message, {
+      cause: options.cause
+    });
+    this.name = "ResolverError";
+    this.code = options.code;
+    this.statusCode = options.statusCode;
+    this.body = options.body;
+    Error.captureStackTrace?.(this, _ResolverError);
+  }
+  static is(error, code) {
+    const isResolverError = error instanceof _ResolverError;
+    return code ? isResolverError && error.code === code : isResolverError;
+  }
+};
+
+// src/types/http.types.ts
+var HttpTypes;
+((HttpTypes2) => {
+  let Status;
+  ((Status2) => {
+    Status2[Status2["UNAUTHORIZED"] = 401] = "UNAUTHORIZED";
+    Status2[Status2["NOT_FOUND"] = 404] = "NOT_FOUND";
+    Status2[Status2["TOO_MANY_REQUESTS"] = 429] = "TOO_MANY_REQUESTS";
+    Status2[Status2["INTERNAL_SERVER_ERROR"] = 500] = "INTERNAL_SERVER_ERROR";
+  })(Status = HttpTypes2.Status || (HttpTypes2.Status = {}));
+})(HttpTypes || (HttpTypes = {}));
+
+// src/client/http.client.ts
+var HttpClient = class _HttpClient {
+  constructor(config) {
+    this.config = config;
+  }
+  static isRetryable(status) {
+    return status === HttpTypes.Status.TOO_MANY_REQUESTS || status >= HttpTypes.Status.INTERNAL_SERVER_ERROR;
+  }
+  static wait(delayInMs) {
+    return new Promise((resolve2) => {
+      setTimeout(resolve2, delayInMs);
+    });
+  }
+  async getJson(path, notFoundCode) {
+    const response = await this.request(path, notFoundCode);
+    const body = await response.json();
+    return body.data ?? body;
+  }
+  async request(path, notFoundCode = ErrorTypes.Code.REQUEST_FAILED) {
+    const url = UrlUtils.join(this.config.baseUrl, path);
+    const response = await this.sendWithRetries(url);
+    if (response.ok) return response;
+    const status = response.status;
+    throw new ResolverError(
+      `Design tokens request failed: ${status} ${url}`,
+      {
+        code: status === HttpTypes.Status.NOT_FOUND ? notFoundCode : ErrorTypes.Code.REQUEST_FAILED,
+        statusCode: status,
+        body: await response.text()
+      }
+    );
+  }
+  async sendWithRetries(url) {
+    let attempt = 0;
+    while (true) {
+      const isLast = attempt >= this.config.retryCount;
+      try {
+        const response = await this.send(url);
+        if (isLast || !_HttpClient.isRetryable(response.status)) return response;
+      } catch (error) {
+        if (isLast) throw error;
+      }
+      attempt += 1;
+      await _HttpClient.wait(this.config.retryDelayInMs * attempt);
+    }
+  }
+  async send(url) {
+    try {
+      return await fetch(url, {
+        headers: this.toHeaders(),
+        signal: AbortSignal.timeout(this.config.requestTimeoutInMs)
+      });
+    } catch (error) {
+      throw new ResolverError(
+        `Design tokens request failed: ${url}`,
+        {
+          code: ErrorTypes.Code.REQUEST_FAILED,
+          cause: error
+        }
+      );
+    }
+  }
+  toHeaders() {
+    const headers = {};
+    if (this.config.apiKey) {
+      headers[httpHeaders.apiKey] = this.config.apiKey;
+    }
+    if (this.config.auth) {
+      const credentials = Buffer.from(`${this.config.auth.username}:${this.config.auth.password}`).toString("base64");
+      headers[httpHeaders.authorization] = `Basic ${credentials}`;
+    }
+    return headers;
+  }
+};
+
+// src/client/design.client.ts
+var DesignClient = class extends HttpClient {
+  async getRelease(version) {
+    return this.getJson(
+      designPaths.release + UrlUtils.toQuery({
+        version
+      }),
+      ErrorTypes.Code.RELEASE_NOT_FOUND
+    );
+  }
+  async getChannel(slug) {
+    return this.getJson(
+      designPaths.channel + UrlUtils.toQuery({
+        slug
+      }),
+      ErrorTypes.Code.RELEASE_NOT_FOUND
+    );
+  }
+  async getDocument(version) {
+    const payload = await this.getJson(
+      designPaths.releasePayload + UrlUtils.toQuery({
+        version
+      }),
+      ErrorTypes.Code.RELEASE_NOT_FOUND
+    );
+    return payload.document;
+  }
+};
+
+// src/core/config.resolver.ts
+var ConfigResolver = class _ConfigResolver {
+  static withDefaults(config) {
+    const baseUrl = _ConfigResolver.toBaseUrl(config);
+    _ConfigResolver.validateAuth(config);
+    return {
+      baseUrl,
+      auth: config.auth ?? null,
+      apiKey: config.apiKey ?? null,
+      requestTimeoutInMs: config.requestTimeoutInMs ?? designDefaults.requestTimeoutInMs,
+      retryCount: config.retryCount ?? designDefaults.retryCount,
+      retryDelayInMs: config.retryDelayInMs ?? designDefaults.retryDelayInMs
+    };
+  }
+  static toBaseUrl(config) {
+    if (config.baseUrl) return config.baseUrl;
+    const env = config.env ?? designDefaults.env;
+    const baseUrl = engineBaseUrls[env];
+    if (!baseUrl) {
+      throw new ResolverError(
+        `Unknown environment "${env}". Known: ${Object.keys(engineBaseUrls).join(", ")}`,
+        {
+          code: ErrorTypes.Code.CONFIG_INVALID
+        }
+      );
+    }
+    return baseUrl;
+  }
+  static validateAuth(config) {
+    if (!config.auth) return;
+    if (config.auth.username && config.auth.password) return;
+    throw new ResolverError(
+      'Design tokens config is invalid: both "username" and "password" are required for basic auth',
+      {
+        code: ErrorTypes.Code.CONFIG_INVALID
+      }
+    );
+  }
+};
+
+// src/core/config-file.resolver.ts
+import {
+  existsSync,
+  readFileSync
+} from "node:fs";
+import {
+  dirname,
+  join,
+  parse,
+  resolve
+} from "node:path";
+import { pathToFileURL } from "node:url";
+var ConfigFileResolver = class _ConfigFileResolver {
+  static async load(startPath) {
+    const path = _ConfigFileResolver.find(startPath);
+    if (!path) return null;
+    return {
+      path,
+      config: await _ConfigFileResolver.read(path)
+    };
+  }
+  static find(startPath) {
+    let current = resolve(startPath);
+    const stopAt = parse(current).root;
+    let found = _ConfigFileResolver.findIn(current);
+    while (!found && current !== stopAt) {
+      current = dirname(current);
+      found = _ConfigFileResolver.findIn(current);
+    }
+    return found;
+  }
+  static findIn(directory) {
+    for (const name of designConfigFiles) {
+      const path = join(directory, name);
+      if (existsSync(path)) return path;
+    }
+    return null;
+  }
+  static async read(path) {
+    try {
+      return path.endsWith(JSON_CONFIG_SUFFIX) ? _ConfigFileResolver.readJson(path) : await _ConfigFileResolver.readModule(path);
+    } catch (error) {
+      if (ResolverError.is(error)) throw error;
+      throw new ResolverError(
+        `Failed to read design tokens config at ${path}`,
+        {
+          code: ErrorTypes.Code.CONFIG_INVALID,
+          cause: error
+        }
+      );
+    }
+  }
+  static readJson(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+  }
+  static async readModule(path) {
+    const imported = await import(pathToFileURL(path).href);
+    const exported = imported.default;
+    if (!exported) {
+      throw new ResolverError(
+        `Design tokens config at ${path} has no default export`,
+        {
+          code: ErrorTypes.Code.CONFIG_INVALID
+        }
+      );
+    }
+    return typeof exported === "function" ? await exported() : exported;
+  }
+};
+
+// src/constants/document.constants.ts
+var DOCUMENT_PATH_SEPARATOR = ".";
+var DOCUMENT_VALUE_KEY_SEPARATOR = ":";
+var DOCUMENT_MAX_ALIAS_DEPTH = 20;
+var DOCUMENT_ALIAS_VALUE_GROUP = 1;
+
+// src/types/config.types.ts
+var ConfigTypes;
+((ConfigTypes2) => {
+  let Format;
+  ((Format2) => {
+    Format2["FLAT"] = "FLAT";
+    Format2["DTCG"] = "DTCG";
+  })(Format = ConfigTypes2.Format || (ConfigTypes2.Format = {}));
+  let Env;
+  ((Env2) => {
+    Env2["LOCAL"] = "local";
+    Env2["DEVELOPMENT"] = "development";
+    Env2["PRODUCTION"] = "production";
+  })(Env = ConfigTypes2.Env || (ConfigTypes2.Env = {}));
+})(ConfigTypes || (ConfigTypes = {}));
+
+// src/mappers/resolve.mapper.ts
+var ResolveMapper = class _ResolveMapper {
+  static toScope(document) {
+    const modes = {};
+    for (const collection of document.collections) {
+      const defaultMode = collection.modes.find((mode) => mode.isDefault) ?? collection.modes[0];
+      if (!defaultMode) continue;
+      modes[collection.slug] = {
+        slugs: new Set(collection.modes.map((mode) => mode.slug)),
+        defaultSlug: defaultMode.slug
+      };
+    }
+    const literals = {};
+    for (const token of document.tokens) {
+      literals[_ResolveMapper.toLiteralKey(token.collection, token.mode, token.path)] = token.$value;
+    }
+    return {
+      literals,
+      modes
+    };
+  }
+  static toLiteralKey(collection, mode, path) {
+    return [collection, mode, path].join(DOCUMENT_VALUE_KEY_SEPARATOR);
+  }
+  static toTarget(alias, state) {
+    const separatorIndex = alias.indexOf(DOCUMENT_PATH_SEPARATOR);
+    if (separatorIndex <= 0) return null;
+    const collection = alias.slice(0, separatorIndex);
+    const collectionModes = state.scope.modes[collection];
+    if (!collectionModes) return null;
+    return {
+      path: alias.slice(separatorIndex + 1),
+      point: {
+        collection,
+        mode: collectionModes.slugs.has(state.point.mode) ? state.point.mode : collectionModes.defaultSlug
+      }
+    };
+  }
+};
+
+// src/utils/resolve.utils.ts
+var ResolveUtils = class _ResolveUtils {
+  static resolve(value, state) {
+    if (state.depth >= DOCUMENT_MAX_ALIAS_DEPTH) return value;
+    if (typeof value === "string") return _ResolveUtils.resolveAlias(value, state);
+    const deeper = {
+      ...state,
+      depth: state.depth + 1
+    };
+    if (Array.isArray(value)) {
+      return value.map((item) => _ResolveUtils.resolve(item, deeper));
+    }
+    if (value === null || typeof value !== "object") return value;
+    const result = {};
+    for (const key of Object.keys(value)) {
+      result[key] = _ResolveUtils.resolve(value[key], deeper);
+    }
+    return result;
+  }
+  static parseAlias(value) {
+    const match = value.trim().match(regularExpressions.dtcgAlias);
+    return match ? match[DOCUMENT_ALIAS_VALUE_GROUP].trim() : null;
+  }
+  static resolveAlias(value, state) {
+    const alias = _ResolveUtils.parseAlias(value);
+    if (!alias) return value;
+    const target = ResolveMapper.toTarget(alias, state);
+    if (!target) return value;
+    const literal = state.scope.literals[ResolveMapper.toLiteralKey(
+      target.point.collection,
+      target.point.mode,
+      target.path
+    )];
+    if (literal === void 0) return value;
+    return _ResolveUtils.resolve(literal, {
+      scope: state.scope,
+      point: target.point,
+      depth: state.depth + 1
+    });
+  }
+};
+
+// src/mappers/document.mapper.ts
+var DocumentMapper = class _DocumentMapper {
+  static toJson(canonical, query) {
+    if (_DocumentMapper.isCanonical(query)) return canonical;
+    const document = JSON.parse(canonical);
+    const output = _DocumentMapper.toOutput(document, query);
+    return `${JSON.stringify(output, null, JSON_INDENT)}${LINE_BREAK}`;
+  }
+  static toOutput(document, query) {
+    if (query.format !== ConfigTypes.Format.DTCG) {
+      return _DocumentMapper.toFlatDocument(document, query);
+    }
+    if (query.collection) return _DocumentMapper.toDtcg(document, query);
+    const trees = {};
+    for (const collection of document.collections) {
+      trees[collection.slug] = _DocumentMapper.toDtcg(document, {
+        ...query,
+        collection: collection.slug
+      });
+    }
+    return trees;
+  }
+  static isCanonical(query) {
+    return !query.collection && !query.resolve && (!query.format || query.format === ConfigTypes.Format.FLAT);
+  }
+  static toFlatDocument(document, query) {
+    return {
+      schemaVersion: document.schemaVersion,
+      collections: query.collection ? document.collections.filter((item) => item.slug === query.collection) : document.collections,
+      tokens: _DocumentMapper.toTokens(document, query)
+    };
+  }
+  static toTokens(document, query) {
+    const tokens = query.collection ? document.tokens.filter((token) => token.collection === query.collection) : document.tokens;
+    if (!query.resolve) return tokens;
+    const scope = ResolveMapper.toScope(document);
+    return tokens.map((token) => ({
+      ...token,
+      $value: ResolveUtils.resolve(token.$value, {
+        scope,
+        point: {
+          collection: token.collection,
+          mode: token.mode
+        },
+        depth: 0
+      })
+    }));
+  }
+  static toDtcg(document, query) {
+    const collection = document.collections.find(
+      (item) => item.slug === query.collection
+    );
+    if (!collection) return {};
+    const byMode = _DocumentMapper.groupByMode(
+      _DocumentMapper.toTokens(document, query)
+    );
+    if (collection.modes.length <= 1) {
+      const [mode] = collection.modes;
+      return _DocumentMapper.toTree(byMode[mode?.slug] ?? []);
+    }
+    const root = {};
+    for (const mode of collection.modes) {
+      root[mode.name] = _DocumentMapper.toTree(byMode[mode.slug] ?? []);
+    }
+    return root;
+  }
+  static groupByMode(tokens) {
+    const grouped = {};
+    for (const token of tokens) {
+      grouped[token.mode] ??= [];
+      grouped[token.mode].push(token);
+    }
+    return grouped;
+  }
+  static toTree(tokens) {
+    const root = {};
+    for (const token of tokens) {
+      const segments = token.path.split(DOCUMENT_PATH_SEPARATOR);
+      const leaf = segments.pop();
+      if (!leaf) continue;
+      let cursor = root;
+      for (const segment of segments) {
+        const next = cursor[segment];
+        if (!next || typeof next !== "object") {
+          cursor[segment] = {};
+        }
+        cursor = cursor[segment];
+      }
+      cursor[leaf] = {
+        $type: token.$type,
+        $value: token.$value
+      };
+    }
+    return root;
+  }
+};
+
+// src/mappers/lock.mapper.ts
+var LockMapper = class {
+  static toLock(release, source) {
+    return {
+      version: release.version,
+      contentHash: release.contentHash,
+      baseUrl: source.baseUrl,
+      byteSize: release.byteSize,
+      publishedAt: release.createdAt,
+      publishedBy: release.publishedBy,
+      sourceLabel: release.sourceLabel
+    };
+  }
+  static toJson(lock) {
+    return `${JSON.stringify(lock, null, JSON_INDENT)}${LINE_BREAK}`;
+  }
+};
+
+// src/utils/file.utils.ts
+import {
+  mkdirSync,
+  writeFileSync
+} from "node:fs";
+import {
+  dirname as dirname2,
+  join as join2
+} from "node:path";
+var FileUtils = class {
+  static write(outputPath, fileName, body) {
+    const target = join2(outputPath, fileName);
+    try {
+      mkdirSync(dirname2(target), {
+        recursive: true
+      });
+      writeFileSync(target, body, "utf8");
+      return target;
+    } catch (error) {
+      throw new ResolverError(
+        `Failed to write design tokens to ${target}`,
+        {
+          code: ErrorTypes.Code.WRITE_FAILED,
+          cause: error
+        }
+      );
+    }
+  }
+};
+
+// src/utils/hash.utils.ts
+import { createHash } from "node:crypto";
+var HashUtils = class {
+  static toContentHash(body) {
+    return createHash(HASH_ALGORITHM).update(body, "utf8").digest(HASH_ENCODING);
+  }
+};
+
+// src/core/design-tokens-resolver.ts
+var DesignTokensResolver = class _DesignTokensResolver {
+  client;
+  config;
+  constructor(config) {
+    this.config = ConfigResolver.withDefaults(config);
+    this.client = new DesignClient(this.config);
+  }
+  static checkIntegrity(release, canonical) {
+    const actual = HashUtils.toContentHash(canonical);
+    if (actual === release.contentHash) return;
+    throw new ResolverError(
+      `Design tokens integrity check failed for ${release.version}: expected ${release.contentHash}, got ${actual}`,
+      {
+        code: ErrorTypes.Code.INTEGRITY_MISMATCH
+      }
+    );
+  }
+  getSource() {
+    return {
+      baseUrl: this.config.baseUrl
+    };
+  }
+  async resolveVersion(target) {
+    if (target.version) return target.version;
+    if (!target.channel) {
+      throw new ResolverError(
+        'Either "version" or "channel" must be provided',
+        {
+          code: ErrorTypes.Code.CONFIG_INVALID
+        }
+      );
+    }
+    const channel = await this.client.getChannel(target.channel);
+    if (channel.version) return channel.version;
+    throw new ResolverError(
+      `Channel "${target.channel}" does not point at any version yet`,
+      {
+        code: ErrorTypes.Code.CHANNEL_EMPTY
+      }
+    );
+  }
+  async fetchVerified(target) {
+    const version = await this.resolveVersion(target);
+    const release = await this.client.getRelease(version);
+    const canonical = await this.client.getDocument(version);
+    _DesignTokensResolver.checkIntegrity(release, canonical);
+    return {
+      release,
+      body: DocumentMapper.toJson(canonical, target)
+    };
+  }
+  async resolve(request) {
+    const verified = await this.fetchVerified(request);
+    const tokensPath = FileUtils.write(
+      request.outputPath,
+      request.fileName ?? designDefaults.fileName,
+      verified.body
+    );
+    const lockPath = request.lock === false ? null : FileUtils.write(
+      request.outputPath,
+      designDefaults.lockFileName,
+      LockMapper.toJson(LockMapper.toLock(verified.release, this.getSource()))
+    );
+    return {
+      release: verified.release,
+      source: this.getSource(),
+      tokensPath,
+      lockPath,
+      bytesWritten: Buffer.byteLength(verified.body, "utf8")
+    };
+  }
+};
+
+// src/constants/cli.constants.ts
+var FLAG_PREFIX = "--";
+var NEGATIVE_FLAG_PREFIX = "--no-";
+
+// src/utils/args.utils.ts
+var ArgsUtils = class _ArgsUtils {
+  static parse(args) {
+    const parsed = {};
+    for (let index = 0; index < args.length; index += 1) {
+      const token = args[index];
+      if (!token?.startsWith(FLAG_PREFIX)) continue;
+      if (token.startsWith(NEGATIVE_FLAG_PREFIX)) {
+        parsed[_ArgsUtils.toKey(token.slice(NEGATIVE_FLAG_PREFIX.length))] = false;
+        continue;
+      }
+      const name = _ArgsUtils.toKey(token.slice(FLAG_PREFIX.length));
+      const next = args[index + 1];
+      if (!next || next.startsWith(FLAG_PREFIX)) {
+        parsed[name] = true;
+        continue;
+      }
+      parsed[name] = next;
+      index += 1;
+    }
+    return parsed;
+  }
+  static toFormat(value) {
+    if (typeof value !== "string") return;
+    const normalized = value.trim().toUpperCase();
+    return normalized === ConfigTypes.Format.DTCG ? ConfigTypes.Format.DTCG : ConfigTypes.Format.FLAT;
+  }
+  static toEnv(value) {
+    return _ArgsUtils.toNormalized(value);
+  }
+  static toText(value) {
+    return typeof value === "string" ? value : void 0;
+  }
+  static toNormalized(value) {
+    if (typeof value !== "string") return;
+    return value.trim().toLowerCase();
+  }
+  static toKey(name) {
+    return name.replace(
+      regularExpressions.kebabSegment,
+      (_, letter) => letter.toUpperCase()
+    );
+  }
+};
+export {
+  ArgsUtils,
+  ConfigFileResolver,
+  ConfigResolver,
+  ConfigTypes,
+  DesignClient,
+  DesignTokensResolver,
+  DocumentMapper,
+  ErrorTypes,
+  FileUtils,
+  HashUtils,
+  HttpClient,
+  HttpTypes,
+  LockMapper,
+  ResolveMapper,
+  ResolveUtils,
+  ResolverError,
+  UrlUtils,
+  DesignTokensResolver as default
+};