50 lines
2.2 KiB
Go
50 lines
2.2 KiB
Go
// Package common contains cross-provider helper code used by weatherfeeder normalizers.
|
|
//
|
|
// Purpose
|
|
// -------
|
|
// Normalizers convert provider-specific RAW payloads into canonical internal/model types.
|
|
// Some small utilities are naturally reusable across multiple providers (unit conversions,
|
|
// payload extraction, common parsing, shared fallbacks). Those belong here.
|
|
//
|
|
// This package is intentionally "boring":
|
|
// - pure helpers (deterministic, no I/O)
|
|
// - minimal abstractions (prefer straightforward functions)
|
|
// - easy to unit test
|
|
//
|
|
// What belongs here
|
|
// -----------------
|
|
// Put code in internal/normalizers/common when it is:
|
|
//
|
|
// - potentially reusable by more than one provider
|
|
// - provider-agnostic (no NWS/OpenWeather/Open-Meteo specific assumptions)
|
|
// - stable, small, and readable
|
|
//
|
|
// Typical examples:
|
|
// - unit conversion helpers (°F <-> °C, m/s <-> km/h, hPa <-> Pa, etc.)
|
|
// - json.RawMessage payload extraction helpers (with good error messages)
|
|
// - shared parsing helpers (timestamps, simple numeric coercions)
|
|
// - generic fallbacks (e.g., mapping a human text description into a coarse canonical code),
|
|
// so long as the logic truly applies across providers
|
|
//
|
|
// What does NOT belong here
|
|
// -------------------------
|
|
// Do NOT put the following in this package:
|
|
//
|
|
// - Normalizer implementations (types that satisfy feedkit/normalize.Normalizer)
|
|
// - provider-specific JSON structs or mapping logic (put those under
|
|
// internal/normalizers/<provider>/)
|
|
// - network or filesystem I/O (sources fetch; normalizers transform)
|
|
// - code that depends on event.Source naming, config fields, or driver-specific params
|
|
//
|
|
// Style and API guidelines
|
|
// ------------------------
|
|
// - Prefer small, single-purpose functions.
|
|
// - Keep function names explicit (avoid clever generic “DoThing” helpers).
|
|
// - Return typed errors with context (include schema/field names where helpful).
|
|
// - Keep dependencies minimal: standard library + weatherfeeder packages only.
|
|
// - Add unit tests for any non-trivial logic (especially parsing and fallbacks).
|
|
//
|
|
// Keeping this clean matters: common is shared by all providers, so complexity here
|
|
// multiplies across the project.
|
|
package common
|