@meterapp/vehicle-db 2.6.0 → 2.7.0

package/dist/index.d.ts

@@ -48,6 +48,52 @@ export interface GetAvailableYearsOptions {
     modelId?: number;
     sourceId?: string;
 }
+export interface VehicleYearRange {
+    yearFrom: number;
+    yearTo: number;
+}
+/**
+ * A sourced period in which a model shares one exterior design. Ranges may
+ * overlap when a facelift, body variant, or regional model changed during a
+ * calendar year; callers must not treat an overlap as render-equivalent.
+ */
+export interface VehicleAppearanceRange {
+    appearanceId: string;
+    makeId: number;
+    makeName: string;
+    modelName: string;
+    label: string;
+    bodyStyle: string;
+    yearFrom: number;
+    yearTo: number;
+    representativeYear: number;
+    regions: string[];
+    sourceName: string;
+    sourceUrl: string;
+}
+export interface GetModelAppearanceRangesOptions {
+    makeId: number;
+    modelName: string;
+    year?: number;
+}
+export interface GetModelRenderGroupsOptions extends GetModelAppearanceRangesOptions {
+    vehicleTypeId?: number;
+    sourceId?: string;
+}
+/**
+ * Safe cache groups for every available year. Sourced, unambiguous appearance
+ * periods are grouped; unknown and overlapping years deliberately stay as
+ * singleton exact-year groups.
+ */
+export interface VehicleRenderGroup {
+    groupId: string;
+    kind: "appearance" | "year";
+    years: number[];
+    yearFrom: number;
+    yearTo: number;
+    representativeYear: number;
+    appearance?: VehicleAppearanceRange;
+}
 /**
  * Returns all vehicle types in the database.
  */
@@ -68,3 +114,23 @@ export declare function getModels(options?: GetModelsOptions): Model[];
  * Gets available years, optionally filtered by vehicle identity and source.
  */
 export declare function getAvailableYears(options?: GetAvailableYearsOptions): number[];
+/**
+ * Compresses available catalog years into contiguous ranges. These ranges
+ * describe availability only; use getModelAppearanceRanges when exterior
+ * equivalence matters.
+ */
+export declare function getAvailableYearRanges(options?: GetAvailableYearsOptions): VehicleYearRange[];
+/** Returns the curated, source-backed exterior-design periods for a model. */
+export declare function getModelAppearanceRanges(options: GetModelAppearanceRangesOptions): VehicleAppearanceRange[];
+/**
+ * Returns a complete, non-overlapping render plan for a model. A year is only
+ * grouped when exactly one verified appearance range contains it.
+ */
+export declare function getModelRenderGroups(options: GetModelRenderGroupsOptions): VehicleRenderGroup[];
+/**
+ * Canonical year for cache/storage identity. Unknown, unavailable, and
+ * ambiguous years return themselves, which is the fail-closed behavior.
+ */
+export declare function getRepresentativeYear(options: GetModelRenderGroupsOptions & {
+    year: number;
+}): number;

package/dist/index.js

@@ -8,6 +8,10 @@ exports.getDataSources = getDataSources;
 exports.getMakes = getMakes;
 exports.getModels = getModels;
 exports.getAvailableYears = getAvailableYears;
+exports.getAvailableYearRanges = getAvailableYearRanges;
+exports.getModelAppearanceRanges = getModelAppearanceRanges;
+exports.getModelRenderGroups = getModelRenderGroups;
+exports.getRepresentativeYear = getRepresentativeYear;
 const data_1 = __importDefault(require("./data"));
 // ---------------------------------------------------------------------------
 // Internal lookup maps (lazy)
@@ -41,6 +45,56 @@ function getSourceIds(sourceMask) {
     }
     return sourceIds;
 }
+function normalizeLookupName(value) {
+    return value.trim().toLocaleUpperCase("en-US").replace(/\s+/g, " ");
+}
+function compactYears(years) {
+    const sorted = [...new Set(years)].sort((left, right) => left - right);
+    const ranges = [];
+    for (const year of sorted) {
+        const previous = ranges[ranges.length - 1];
+        if (previous && previous.yearTo + 1 === year)
+            previous.yearTo = year;
+        else
+            ranges.push({ yearFrom: year, yearTo: year });
+    }
+    return ranges;
+}
+function modelNameYears(options) {
+    const sourceMask = options.sourceId == null ? undefined : getSourceMaskMap().get(options.sourceId);
+    if (options.sourceId != null && sourceMask == null)
+        return [];
+    const wantedModel = normalizeLookupName(options.modelName);
+    const years = new Set();
+    for (const model of data_1.default.models) {
+        if (model[1] !== options.makeId)
+            continue;
+        if (options.vehicleTypeId != null && model[4] !== options.vehicleTypeId)
+            continue;
+        if (sourceMask != null && (model[5] & sourceMask) === 0)
+            continue;
+        if (normalizeLookupName(data_1.default.modelNames[model[3]]) !== wantedModel)
+            continue;
+        years.add(model[0]);
+    }
+    return [...years].sort((left, right) => left - right);
+}
+function toAppearanceRange(range) {
+    return {
+        appearanceId: range.id,
+        makeId: range.make_id,
+        makeName: range.make_name,
+        modelName: range.model_name,
+        label: range.label,
+        bodyStyle: range.body_style,
+        yearFrom: range.year_from,
+        yearTo: range.year_to,
+        representativeYear: range.representative_year,
+        regions: [...range.regions],
+        sourceName: range.source_name,
+        sourceUrl: range.source_url,
+    };
+}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -156,3 +210,70 @@ function getAvailableYears(options = {}) {
     }
     return [...years].sort((a, b) => a - b);
 }
+/**
+ * Compresses available catalog years into contiguous ranges. These ranges
+ * describe availability only; use getModelAppearanceRanges when exterior
+ * equivalence matters.
+ */
+function getAvailableYearRanges(options = {}) {
+    return compactYears(getAvailableYears(options));
+}
+/** Returns the curated, source-backed exterior-design periods for a model. */
+function getModelAppearanceRanges(options) {
+    const wantedModel = normalizeLookupName(options.modelName);
+    return data_1.default.appearanceRanges
+        .filter((range) => range.make_id === options.makeId &&
+        normalizeLookupName(range.model_name) === wantedModel &&
+        (options.year == null ||
+            (range.year_from <= options.year && range.year_to >= options.year)))
+        .map(toAppearanceRange);
+}
+/**
+ * Returns a complete, non-overlapping render plan for a model. A year is only
+ * grouped when exactly one verified appearance range contains it.
+ */
+function getModelRenderGroups(options) {
+    const years = modelNameYears(options);
+    const appearances = getModelAppearanceRanges(options);
+    const groupYears = new Map();
+    const appearanceByGroup = new Map();
+    for (const year of years) {
+        const candidates = appearances.filter((appearance) => appearance.yearFrom <= year && appearance.yearTo >= year);
+        const groupId = candidates.length === 1 ? candidates[0].appearanceId : `year:${year}`;
+        const existing = groupYears.get(groupId);
+        if (existing)
+            existing.push(year);
+        else
+            groupYears.set(groupId, [year]);
+        if (candidates.length === 1)
+            appearanceByGroup.set(groupId, candidates[0]);
+    }
+    return [...groupYears.entries()]
+        .map(([groupId, groupedYears]) => {
+        const appearance = appearanceByGroup.get(groupId);
+        const preferred = appearance?.representativeYear;
+        const representativeYear = preferred != null && groupedYears.includes(preferred)
+            ? preferred
+            : groupedYears.reduce((best, year) => preferred != null && Math.abs(year - preferred) < Math.abs(best - preferred)
+                ? year
+                : best);
+        return {
+            groupId,
+            kind: appearance ? "appearance" : "year",
+            years: [...groupedYears],
+            yearFrom: groupedYears[0],
+            yearTo: groupedYears[groupedYears.length - 1],
+            representativeYear,
+            ...(appearance ? { appearance } : {}),
+        };
+    })
+        .sort((left, right) => left.yearFrom - right.yearFrom || left.yearTo - right.yearTo);
+}
+/**
+ * Canonical year for cache/storage identity. Unknown, unavailable, and
+ * ambiguous years return themselves, which is the fail-closed behavior.
+ */
+function getRepresentativeYear(options) {
+    const group = getModelRenderGroups(options).find((candidate) => candidate.years.includes(options.year));
+    return group?.representativeYear ?? options.year;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meterapp/vehicle-db",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Offline international database for cars, motorcycles, trucks, buses, MPVs, and more",
   "repository": {
     "type": "git",