@meterapp/vehicle-db 2.5.0 → 2.7.0

package/dist/index.d.ts

@@ -39,8 +39,61 @@ export interface GetModelsOptions {
     year?: number;
     vehicleTypeId?: number;
     makeId?: number;
+    modelId?: number;
     sourceId?: string;
 }
+export interface GetAvailableYearsOptions {
+    vehicleTypeId?: number;
+    makeId?: number;
+    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.
  */
@@ -58,6 +111,26 @@ export declare function getMakes(options?: GetMakesOptions): Make[];
  */
 export declare function getModels(options?: GetModelsOptions): Model[];
 /**
- * Get all available years in the database.
+ * 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 getAvailableYears(): number[];
+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
 // ---------------------------------------------------------------------------
@@ -105,7 +159,7 @@ function getMakes(options = {}) {
 function getModels(options = {}) {
     const makeMap = getMakeMap();
     const typeMap = getTypeMap();
-    const { year, vehicleTypeId, makeId, sourceId } = options;
+    const { year, vehicleTypeId, makeId, modelId, sourceId } = options;
     const sourceMask = sourceId == null ? undefined : getSourceMaskMap().get(sourceId);
     if (sourceId != null && sourceMask == null)
         return [];
@@ -115,6 +169,8 @@ function getModels(options = {}) {
             continue;
         if (makeId != null && m[1] !== makeId)
             continue;
+        if (modelId != null && m[2] !== modelId)
+            continue;
         if (vehicleTypeId != null && m[4] !== vehicleTypeId)
             continue;
         if (sourceMask != null && (m[5] & sourceMask) === 0)
@@ -133,12 +189,91 @@ function getModels(options = {}) {
         a.vehicleTypeId - b.vehicleTypeId);
 }
 /**
- * Get all available years in the database.
+ * Gets available years, optionally filtered by vehicle identity and source.
  */
-function getAvailableYears() {
+function getAvailableYears(options = {}) {
+    const { vehicleTypeId, makeId, modelId, sourceId } = options;
+    const sourceMask = sourceId == null ? undefined : getSourceMaskMap().get(sourceId);
+    if (sourceId != null && sourceMask == null)
+        return [];
     const years = new Set();
     for (const m of data_1.default.models) {
+        if (makeId != null && m[1] !== makeId)
+            continue;
+        if (modelId != null && m[2] !== modelId)
+            continue;
+        if (vehicleTypeId != null && m[4] !== vehicleTypeId)
+            continue;
+        if (sourceMask != null && (m[5] & sourceMask) === 0)
+            continue;
         years.add(m[0]);
     }
     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/dist/search.d.ts

@@ -0,0 +1,47 @@
+export type VehicleSearchMatchKind = "exact" | "prefix" | "token" | "contains" | "fuzzy";
+export interface SearchVehiclesOptions {
+    /** Restrict results to one catalog year. A year in the query is detected automatically. */
+    year?: number;
+    vehicleTypeId?: number;
+    sourceId?: string;
+    /** Maximum number of results. Defaults to 10 and is capped at 100. */
+    limit?: number;
+    /** Enables conservative typo matching. Defaults to true. */
+    fuzzy?: boolean;
+}
+interface VehicleSearchResultBase {
+    makeId: number;
+    makeName: string;
+    /** Available years after applying the supplied filters, sorted ascending. */
+    years: number[];
+    sourceIds: string[];
+    matchKind: VehicleSearchMatchKind;
+}
+export interface VehicleMakeSearchResult extends VehicleSearchResultBase {
+    kind: "make";
+}
+export interface VehicleSearchVariant {
+    year: number;
+    /** The preferred catalog model ID for this canonical make/model/type/year. */
+    modelId: number;
+    sourceIds: string[];
+}
+export interface VehicleModelSearchResult extends VehicleSearchResultBase {
+    kind: "model";
+    modelName: string;
+    vehicleTypeId: number;
+    vehicleTypeName: string;
+    /** One directly selectable catalog identity per available year. */
+    variants: VehicleSearchVariant[];
+}
+export type VehicleSearchResult = VehicleMakeSearchResult | VehicleModelSearchResult;
+/**
+ * Finds canonical make and model candidates for a driver-entered query.
+ *
+ * Matching is deterministic and popularity-neutral: exact, prefix, token,
+ * substring, then conservative typo matching. Applications can request a
+ * larger candidate set and rerank within the returned `matchKind` using local
+ * recents or regional telemetry.
+ */
+export declare function searchVehicles(query: string, options?: SearchVehiclesOptions): VehicleSearchResult[];
+export {};