@synergy-design-system/metadata 1.0.0 → 3.0.1

package/dist/public/domains/tokens.js

@@ -0,0 +1,165 @@
+import { createMetadataStore } from '../store.js';
+import { layerExistsForEntity, mapEntityForResponse, paginate, readLayerFilesForEntity, sortByEntityId, } from '../utils.js';
+const deriveTokenFormat = (artifactPath) => {
+    if (!artifactPath) {
+        return undefined;
+    }
+    const normalized = artifactPath.toLowerCase();
+    if (normalized.includes('figma-variables/') && normalized.endsWith('.json')) {
+        return 'figma';
+    }
+    if (normalized.endsWith('.scss')) {
+        return 'sass';
+    }
+    if (normalized.endsWith('.js') || normalized.endsWith('.d.ts')) {
+        return 'javascript';
+    }
+    if (normalized.endsWith('.css')) {
+        return 'css';
+    }
+    return undefined;
+};
+const deriveTokenTheme = (artifactPath) => {
+    if (!artifactPath) {
+        return undefined;
+    }
+    const normalized = artifactPath
+        .toLowerCase()
+        .replace(/_/g, '-');
+    if (normalized.includes('sick2025') && normalized.includes('dark')) {
+        return 'sick2025-dark';
+    }
+    if (normalized.includes('sick2025') && normalized.includes('light')) {
+        return 'sick2025-light';
+    }
+    if (normalized.includes('sick2018') && normalized.includes('dark')) {
+        return 'sick2018-dark';
+    }
+    if (normalized.includes('sick2018') && normalized.includes('light')) {
+        return 'sick2018-light';
+    }
+    return undefined;
+};
+/**
+ * List tokens with optional filtering and pagination.
+ * @param options Options for querying tokens, including filtering by status and tags, pagination, and layer/verbosity preferences.
+ * @param storeOptions Options for configuring the metadata store.
+ * @returns A promise that resolves to a public response containing the list of tokens and metadata.
+ */
+export const getTokens = async (options = {}, storeOptions = {}) => {
+    const store = createMetadataStore(storeOptions);
+    const index = await store.getIndex();
+    const requestedLayer = options.layer ?? 'full';
+    const requestedVerbosity = options.verbosity ?? 'readable';
+    const entities = (await store.findEntities({
+        kind: 'token',
+        status: options.status,
+        tags: options.tags,
+    }));
+    const sorted = sortByEntityId(entities);
+    const hasRequestedLayer = sorted.every((entity) => layerExistsForEntity(entity, requestedLayer));
+    if (options.strictLayer && !hasRequestedLayer) {
+        return {
+            data: [],
+            errors: [{
+                    code: 'LAYER_NOT_AVAILABLE',
+                    details: {
+                        requestedLayer,
+                    },
+                    message: `Requested layer "${requestedLayer}" is not available for all token entities.`,
+                }],
+            meta: {
+                builtAt: index.builtAt,
+                requestedLayer,
+                requestedVerbosity,
+                resolvedLayer: requestedLayer,
+                schemaVersion: index.version,
+                total: sorted.length,
+                warnings: ['strictLayer=true and requested layer is unavailable for part of result set'],
+            },
+        };
+    }
+    const resolvedLayer = hasRequestedLayer ? requestedLayer : 'full';
+    const paged = paginate(sorted, options.limit, options.offset);
+    return {
+        data: paged.map((entity) => mapEntityForResponse(entity, options)),
+        meta: {
+            builtAt: index.builtAt,
+            requestedLayer,
+            requestedVerbosity,
+            resolvedLayer,
+            schemaVersion: index.version,
+            total: sorted.length,
+            warnings: hasRequestedLayer ? undefined : [
+                `Requested layer "${requestedLayer}" was unavailable; falling back to "full".`,
+            ],
+        },
+    };
+};
+/**
+ * Get token data for a specific format and theme, with options for pagination.
+ * @param options Options for querying token data, including format, theme, pagination preferences.
+ * @param storeOptions Options for configuring the metadata store.
+ * @returns A promise that resolves to a public response containing the token data payload, or null if not found.
+ */
+export const getDataForTokens = async (options = {}, storeOptions = {}) => {
+    const requestedFormat = options.format ?? 'css';
+    const resolvedTheme = requestedFormat === 'css'
+        ? (options.theme ?? 'sick2025-light')
+        : options.theme;
+    const metadata = await getTokens({
+        includeLayerRefs: true,
+        includeSources: false,
+        layer: 'full',
+    }, storeOptions);
+    const warnings = [];
+    if (requestedFormat !== 'css' && options.theme) {
+        warnings.push(`Theme "${options.theme}" is ignored for format "${requestedFormat}".`);
+    }
+    const filteredEntities = metadata.data.filter((entity) => {
+        const format = (entity.custom?.format)
+            ?? deriveTokenFormat(entity.custom?.artifactPath);
+        const theme = (entity.custom?.theme)
+            ?? deriveTokenTheme(entity.custom?.artifactPath);
+        if (format !== requestedFormat) {
+            return false;
+        }
+        if (requestedFormat === 'css') {
+            return theme === resolvedTheme;
+        }
+        return true;
+    });
+    const pagedEntities = paginate(filteredEntities, options.limit, options.offset);
+    const store = createMetadataStore(storeOptions);
+    const tokenEntries = (await Promise.all(pagedEntities.map(async (entity) => {
+        const files = await readLayerFilesForEntity(store, entity, 'full');
+        const format = (entity.custom?.format)
+            ?? deriveTokenFormat(entity.custom?.artifactPath);
+        const theme = (entity.custom?.theme)
+            ?? deriveTokenTheme(entity.custom?.artifactPath);
+        return files.map(({ content, ref }) => ({
+            content,
+            format,
+            path: ref.path,
+            theme,
+            token: entity.id,
+        }));
+    }))).flat();
+    return {
+        data: {
+            format: requestedFormat,
+            theme: requestedFormat === 'css' ? resolvedTheme : undefined,
+            tokens: tokenEntries,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        },
+        errors: metadata.errors,
+        meta: {
+            ...metadata.meta,
+            total: filteredEntities.length,
+            warnings: [
+                ...(metadata.meta.warnings ?? []),
+                ...warnings,
+            ],
+        },
+    };
+};

package/dist/public/index.d.ts

@@ -0,0 +1,21 @@
+export { clearMetadataStoreCache, createMetadataStore, getMetadataInfo } from './store.js';
+export { getAssetMetadata, listAssets, searchIcons } from './domains/assets.js';
+export { listComponentClusters, listComponentsByCluster } from './domains/clusters.js';
+export { getComponentMetadata, getDataForComponent, listComponents } from './domains/components.js';
+export { getFontMetadata, listFonts } from './domains/fonts.js';
+export { getMigrations } from './domains/migrations.js';
+export { getDataForSetup } from './domains/setup.js';
+export { getDataForStyle, getStyleMetadata, listStyles } from './domains/styles.js';
+export { getTemplateMetadata, getDataForTemplate, listTemplates } from './domains/templates.js';
+export { getDataForTokens, getTokens } from './domains/tokens.js';
+export { collectLayerReferences, readLayerFilesForEntity } from './utils.js';
+export type { AssetQueryOptions, IconSearchOptions } from './domains/assets.js';
+export type { ClusterComponentQueryOptions, ClusterQueryOptions, } from './domains/clusters.js';
+export type { ComponentDataLayer, ComponentDataPayload, ComponentDataQueryOptions, ComponentFramework, ComponentFrameworkDetails, ComponentLayerContent, ComponentQueryOptions, ComponentTextLayerContent, } from './domains/components.js';
+export type { FontQueryOptions } from './domains/fonts.js';
+export type { MigrationQueryOptions } from './domains/migrations.js';
+export type { SetupDataPayload, SetupDataQueryOptions, SetupEntry, SetupPackage, SetupTextLayerContent, } from './domains/setup.js';
+export type { StyleDataLayer, StyleDataPayload, StyleDataQueryOptions, StyleQueryOptions, StyleTextLayerContent, } from './domains/styles.js';
+export type { TemplateDataLayer, TemplateDataPayload, TemplateDataQueryOptions, TemplateQueryOptions, TemplateTextLayerContent, } from './domains/templates.js';
+export type { TokenDataContent, TokenDataPayload, TokenDataQueryOptions, TokenFormat, TokenQueryOptions, TokenTheme, } from './domains/tokens.js';
+export type { AssetCustom, AssetEntity, AssetIconData, AssetIconSetCustom, AssetIconSetEntity, AssetLogoCustom, AssetLogoEntity, AssetSystemIconCustom, AssetSystemIconEntity, ComponentAngularCustom, ComponentCluster, ComponentCustom, ComponentEntity, ComponentInterfaceAttribute, ComponentInterfaceEvent, ComponentInterfaceMethod, ComponentInterfaceProperty, ComponentInterfaceSnapshot, ComponentNamedDescription, ComponentReactJsxCustom, ComponentReactWrapperCustom, ComponentVueCustom, FontCustom, FontEntity, IconFilterMode, IconSearchQuery, IconSearchResult, LayerName, MetadataEntity, MetadataIndex, MetadataIndexEntry, MetadataLayerRef, MetadataQuery, MetadataRelationRef, MetadataStore, MetadataStoreOptions, MigrationCustom, MigrationEntity, SetupCustom, SetupEntity, PublicError, PublicErrorCode, PublicRequestOptions, PublicResponse, PublicResponseMeta, StyleCustom, StyleEntity, TokenCustom, TokenEntity, Verbosity, } from './types.js';

package/dist/public/index.js

@@ -0,0 +1,11 @@
+export { clearMetadataStoreCache, createMetadataStore, getMetadataInfo } from './store.js';
+export { getAssetMetadata, listAssets, searchIcons } from './domains/assets.js';
+export { listComponentClusters, listComponentsByCluster } from './domains/clusters.js';
+export { getComponentMetadata, getDataForComponent, listComponents } from './domains/components.js';
+export { getFontMetadata, listFonts } from './domains/fonts.js';
+export { getMigrations } from './domains/migrations.js';
+export { getDataForSetup } from './domains/setup.js';
+export { getDataForStyle, getStyleMetadata, listStyles } from './domains/styles.js';
+export { getTemplateMetadata, getDataForTemplate, listTemplates } from './domains/templates.js';
+export { getDataForTokens, getTokens } from './domains/tokens.js';
+export { collectLayerReferences, readLayerFilesForEntity } from './utils.js';

package/dist/public/store.d.ts

@@ -0,0 +1,19 @@
+import { type MetadataStore, type MetadataStoreOptions } from './types.js';
+/**
+ * Clears all process-local metadata store caches.
+ * Useful for tests and explicit cache lifecycle control.
+ */
+export declare const clearMetadataStoreCache: () => void;
+/**
+ * Returns the version and build date from the metadata package's index.json.
+ * Useful for exposing metadata version information in HTTP response headers.
+ */
+export declare const getMetadataInfo: () => Promise<{
+    builtAt: string;
+    version: string;
+}>;
+/**
+ * Create a metadata store that can query entities and read layer files.
+ * @param options Optional runtime configuration (for example a custom `dataDir`).
+ */
+export declare const createMetadataStore: (options?: MetadataStoreOptions) => MetadataStore;

package/dist/public/store.js

@@ -0,0 +1,184 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const defaultDataDir = fileURLToPath(new URL('../../data', import.meta.url));
+const indexCacheByDataDir = new Map();
+const indexInflightByDataDir = new Map();
+const entityCacheByPath = new Map();
+const entityInflightByPath = new Map();
+const layerContentCacheByPath = new Map();
+const layerContentInflightByPath = new Map();
+const readJson = async (filePath) => {
+    const raw = await readFile(filePath, 'utf8');
+    return JSON.parse(raw);
+};
+const clone = (value) => structuredClone(value);
+const getCachedJson = async (cache, inflight, key, loader) => {
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+        return clone(cached);
+    }
+    const existingInflight = inflight.get(key);
+    if (existingInflight) {
+        return clone(await existingInflight);
+    }
+    const loadPromise = loader()
+        .then((loaded) => {
+        cache.set(key, loaded);
+        return loaded;
+    })
+        .finally(() => {
+        inflight.delete(key);
+    });
+    inflight.set(key, loadPromise);
+    return clone(await loadPromise);
+};
+const getCachedText = async (cache, inflight, key, loader) => {
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const existingInflight = inflight.get(key);
+    if (existingInflight) {
+        return existingInflight;
+    }
+    const loadPromise = loader()
+        .then((loaded) => {
+        cache.set(key, loaded);
+        return loaded;
+    })
+        .finally(() => {
+        inflight.delete(key);
+    });
+    inflight.set(key, loadPromise);
+    return loadPromise;
+};
+/**
+ * Clears all process-local metadata store caches.
+ * Useful for tests and explicit cache lifecycle control.
+ */
+export const clearMetadataStoreCache = () => {
+    indexCacheByDataDir.clear();
+    indexInflightByDataDir.clear();
+    entityCacheByPath.clear();
+    entityInflightByPath.clear();
+    layerContentCacheByPath.clear();
+    layerContentInflightByPath.clear();
+};
+/**
+ * Returns the version and build date from the metadata package's index.json.
+ * Useful for exposing metadata version information in HTTP response headers.
+ */
+export const getMetadataInfo = async () => {
+    const indexPath = join(defaultDataDir, 'index.json');
+    const index = await getCachedJson(indexCacheByDataDir, indexInflightByDataDir, indexPath, () => readJson(indexPath));
+    return { builtAt: index.builtAt, version: index.version };
+};
+const normalize = (value) => value.trim().toLowerCase();
+const matchesQuery = (entity, query) => {
+    if (query.id && entity.id !== query.id) {
+        return false;
+    }
+    if (query.kind && entity.kind !== query.kind) {
+        return false;
+    }
+    if (query.package && entity.package !== query.package) {
+        return false;
+    }
+    if (query.status && entity.status !== query.status) {
+        return false;
+    }
+    if (query.tags && query.tags.length > 0) {
+        const entityTags = entity.tags.map(normalize);
+        const requested = query.tags.map(normalize);
+        if (!requested.every((tag) => entityTags.includes(tag))) {
+            return false;
+        }
+    }
+    if (query.layer && (!entity.layers || !entity.layers[query.layer] || entity.layers[query.layer].length === 0)) {
+        return false;
+    }
+    return true;
+};
+const buildCoreEntityPath = (dataDir, entry) => join(dataDir, entry.corePath.replace(/^data\//, ''));
+/**
+ * Create a metadata store that can query entities and read layer files.
+ * @param options Optional runtime configuration (for example a custom `dataDir`).
+ */
+export const createMetadataStore = (options = {}) => {
+    const dataDir = options.dataDir ?? defaultDataDir;
+    /**
+     * Load and cache `data/index.json` at process level, scoped by dataDir.
+     */
+    const getIndex = async () => getCachedJson(indexCacheByDataDir, indexInflightByDataDir, join(dataDir, 'index.json'), () => readJson(join(dataDir, 'index.json')));
+    const getEntityFromEntry = async (entry) => {
+        const entityPath = buildCoreEntityPath(dataDir, entry);
+        return getCachedJson(entityCacheByPath, entityInflightByPath, entityPath, () => readJson(entityPath));
+    };
+    /**
+     * Get one entity by exact ID from the metadata index.
+     */
+    const getEntity = async (id) => {
+        const index = await getIndex();
+        const entry = index.entities.find((candidate) => candidate.id === id);
+        if (!entry) {
+            return null;
+        }
+        return getEntityFromEntry(entry);
+    };
+    /**
+     * Find entities by query fields (`kind`, `package`, `status`, `tags`, `layer`, ...).
+     */
+    const findEntities = async (query = {}) => {
+        const index = await getIndex();
+        const filteredEntries = index.entities.filter((entry) => {
+            if (query.id && entry.id !== query.id) {
+                return false;
+            }
+            if (query.kind && entry.kind !== query.kind) {
+                return false;
+            }
+            return true;
+        });
+        const entities = await Promise.all(filteredEntries.map((entry) => getEntityFromEntry(entry)));
+        return entities.filter((entity) => matchesQuery(entity, query));
+    };
+    /**
+     * Return layer references for an entity and layer.
+     * Use `readLayerFile` to resolve each reference to file contents.
+     */
+    const getLayerFiles = async (entityId, layer) => {
+        const entity = await getEntity(entityId);
+        if (!entity || !entity.layers || !entity.layers[layer]) {
+            return [];
+        }
+        return entity.layers[layer] ?? [];
+    };
+    const getPackageEntities = async (packageName) => findEntities({ package: packageName });
+    /**
+     * Return entity IDs and layer references for all entities in a package and layer.
+     */
+    const getDataForLayer = async (packageName, layer) => {
+        const entities = await findEntities({ layer, package: packageName });
+        return entities.map((entity) => ({
+            entityId: entity.id,
+            files: entity.layers?.[layer] ?? [],
+        }));
+    };
+    /**
+     * Read the UTF-8 content for a layer file reference.
+     */
+    const readLayerFile = async (ref) => {
+        const filePath = join(dataDir, ref.path.replace(/^data\//, ''));
+        return getCachedText(layerContentCacheByPath, layerContentInflightByPath, filePath, () => readFile(filePath, 'utf8'));
+    };
+    return {
+        findEntities,
+        getDataForLayer,
+        getEntity,
+        getIndex,
+        getLayerFiles,
+        getPackageEntities,
+        readLayerFile,
+    };
+};