@motionstudies/core 0.1.0-alpha.16 → 0.1.0-alpha.18

package/README.md

@@ -246,6 +246,8 @@ These transport-neutral modules came from Zugunruhe's radar-field studies and se
 
 Render support as opacity or reach, not as confidence in the underlying measurement: it says how far the nearest evidence is, nothing about that evidence's accuracy. The kernel scale is a claim about resolution and belongs in the study's provenance.
 
+`@motionstudies/core/domain/published-day` reads a published day of the national layer as the recording host compiles it: `openPublishedDay` takes a transport (`fetchTransport` over a base URL, or any pair of text and bytes readers) and returns the manifest and index up front, then slices, members and packs on demand and cached per file; `partFor` resolves an operator and vehicle to the pack part that holds it; `sliceNameAt` and `cellOf` reproduce the compiler's slice and cell rules exactly, so a position lands in the cell the compiler put it in; `positionAt` interpolates along a track only inside a tolerated gap, and `journeyAt` finds the run in force at an instant. Packs are gunzipped with the platform's `DecompressionStream` unless an inflater is supplied.
+
 `@motionstudies/core/domain/gridded-series` reads a regular latitude/longitude grid of variables at listed instants. `bracketTime` finds the adjacent frames; `sampleGriddedSeries` interpolates bilinearly in space and linearly in time; `meanGriddedSeries` returns an area-weighted mean, with an optional valid range. A missing sample with any weight makes the reading unavailable instead of bridging the gap. Values keep the source's units; the consumer converts percentages or applies its own scale.
 
 `@motionstudies/core/domain/field-paths` integrates illustrative paths through an estimated velocity field. `advanceFieldPath` takes an explicit midpoint step in metres per second, with `secondsPerStep` converting one unit of study time, and refuses to start from, pass through or land on unsupported field. `mixFieldMovement` blends two readings; `visibleTrailSegments` returns the last `trail` steps of a track at a study time with a fade at either end, identical when scrubbing back. Paths are neither observed trajectories nor individual movers and must be labelled as illustration.

package/domain/published-day.d.ts

@@ -0,0 +1,124 @@
+/** A published day of the national layer, as compiled by the recording host: the sea (one file of 0.1° cells per
+ * five-minute slice), the shoal (one file per slice from cell to member vehicles), and the fish (one gzipped pack
+ * per operator per day, split into parts by sample budget), with an index from operator and vehicle to part and a
+ * manifest of every file. Everything is static; opening one vehicle fetches one pack. Readers supply the transport
+ * and, where the platform lacks DecompressionStream, the inflater; nothing here touches the network itself.
+ */
+export declare const SLICE_SECONDS = 300, CELL_DEGREES = 0.1;
+export interface PublishedDayManifest {
+    readonly date: string;
+    readonly compiledAt: string;
+    readonly hours: {
+        readonly present: readonly string[];
+        readonly missing: readonly string[];
+    };
+    readonly stats: {
+        readonly samples: number;
+        readonly vehicles: number;
+        readonly operators: number;
+        readonly slices: number;
+        readonly excludedRejected: number;
+        readonly excludedOutsideDay: number;
+    };
+    readonly slices: number;
+    readonly files: number;
+    readonly bytes: number;
+    readonly list: readonly {
+        readonly path: string;
+        readonly bytes: number;
+    }[];
+}
+/** One cell of a slice: centre-less floor coordinates, samples (which sum across cells) and distinct vehicles (which do not). */
+export type SliceCell = readonly [lon: number, lat: number, samples: number, vehicles: number];
+export interface SliceFile {
+    readonly slice: string;
+    readonly cells: readonly SliceCell[];
+}
+/** Members of each cell as operator index into the day index and vehicle reference. */
+export type Member = readonly [operatorIndex: number, vehicleRef: string];
+export interface MembersFile {
+    readonly slice: string;
+    readonly cells: Readonly<Record<string, readonly Member[]>>;
+}
+export interface PackPart {
+    readonly file: string;
+    readonly bytes: number;
+    readonly vehicles: number;
+    readonly samples: number;
+    readonly refs?: readonly string[];
+}
+export interface OperatorEntry {
+    readonly ref: string;
+    readonly vehicles: number;
+    readonly samples: number;
+    readonly parts: readonly PackPart[];
+}
+export interface DayIndex {
+    readonly date: string;
+    readonly operators: readonly OperatorEntry[];
+}
+export type TrackPoint = readonly [epochSeconds: number, lon: number, lat: number];
+export type JourneyRun = readonly [epochSeconds: number, lineRef: string | null, journeyRef: string | null];
+export interface VehicleDay {
+    readonly track: readonly TrackPoint[];
+    readonly journeys: readonly JourneyRun[];
+}
+export interface Pack {
+    readonly date: string;
+    readonly operator: string;
+    readonly part: number;
+    readonly parts: number;
+    readonly vehicles: Readonly<Record<string, VehicleDay>>;
+}
+export interface DayTransport {
+    /** Text of a file under the day's base, by its relative path. */
+    readonly text: (path: string) => Promise<string>;
+    /** Bytes of a file under the day's base. */
+    readonly bytes: (path: string) => Promise<Uint8Array>;
+    /** Gunzip; defaults to the platform's DecompressionStream. */
+    readonly inflate?: (bytes: Uint8Array) => Promise<Uint8Array>;
+}
+/** The slice file name for an instant: HH-MM of the five-minute slice containing it, UTC. */
+export declare function sliceNameAt(instant: string | number): string;
+/** The ISO start of a named slice on a date. */
+export declare function sliceStart(date: string, name: string): string;
+/** The cell a position falls in, by the compiler's own rule: floor of the coordinate over the cell size, in double
+ * arithmetic, printed to one decimal. The rule is reproduced exactly rather than rounded, so a position near a
+ * cell edge lands where the compiler put it. */
+export declare function cellOf(lon: number, lat: number): readonly [number, number];
+export declare function cellKey(cellLon: number, cellLat: number): string;
+/** The pack part holding a vehicle: the only part, or the part whose reference list names it. */
+export declare function partFor(index: DayIndex, operatorRef: string, vehicleRef: string): PackPart | null;
+/** Position along a track at an instant: linear between the samples around it, null outside the track or across a
+ * gap longer than the tolerance, so a vehicle that stopped reporting does not glide. */
+export declare function positionAt(track: readonly TrackPoint[], epochSeconds: number, maxGapSeconds?: number): readonly [lon: number, lat: number] | null;
+/** The line and journey a vehicle was on at an instant, from its runs. */
+export declare function journeyAt(journeys: readonly JourneyRun[], epochSeconds: number): JourneyRun | null;
+/** Minimal shapes of the platform pieces used, so the module compiles without DOM typings. */
+interface ByteSource {
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+interface ResponseLike extends ByteSource {
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+}
+export type FetchLike = (url: string) => Promise<ResponseLike>;
+export declare function inflateGzip(bytes: Uint8Array): Promise<Uint8Array>;
+/** Packs are stored gzipped, but a server that declares the encoding hands the browser the decoded bytes; either form is accepted by its first two bytes. */
+export declare function inflateIfGzipped(bytes: Uint8Array, inflate: (bytes: Uint8Array) => Promise<Uint8Array>): Promise<Uint8Array>;
+export interface PublishedDay {
+    readonly manifest: PublishedDayManifest;
+    readonly index: DayIndex;
+    readonly slice: (name: string) => Promise<SliceFile>;
+    readonly members: (name: string) => Promise<MembersFile>;
+    readonly pack: (operatorRef: string, vehicleRef: string) => Promise<Pack>;
+    readonly vehicle: (operatorRef: string, vehicleRef: string) => Promise<VehicleDay | null>;
+    /** Slice names present, from the manifest's file list, in order. */
+    readonly sliceNames: readonly string[];
+}
+/** Open a published day: manifest and index up front, everything else on demand and cached per file. */
+export declare function openPublishedDay(transport: DayTransport): Promise<PublishedDay>;
+/** A transport over fetch for a day served under a base URL. */
+export declare function fetchTransport(base: string, fetchImpl?: FetchLike | undefined): DayTransport;
+export {};

package/domain/published-day.js

@@ -0,0 +1,114 @@
+/** A published day of the national layer, as compiled by the recording host: the sea (one file of 0.1° cells per
+ * five-minute slice), the shoal (one file per slice from cell to member vehicles), and the fish (one gzipped pack
+ * per operator per day, split into parts by sample budget), with an index from operator and vehicle to part and a
+ * manifest of every file. Everything is static; opening one vehicle fetches one pack. Readers supply the transport
+ * and, where the platform lacks DecompressionStream, the inflater; nothing here touches the network itself.
+ */
+export const SLICE_SECONDS = 300, CELL_DEGREES = 0.1;
+/** The slice file name for an instant: HH-MM of the five-minute slice containing it, UTC. */
+export function sliceNameAt(instant) {
+    const t = typeof instant === 'number' ? instant : Date.parse(instant);
+    if (!Number.isFinite(t))
+        throw new Error('Invalid instant');
+    const s = Math.floor(t / 1000 / SLICE_SECONDS) * SLICE_SECONDS, d = new Date(s * 1000);
+    return `${String(d.getUTCHours()).padStart(2, '0')}-${String(d.getUTCMinutes()).padStart(2, '0')}`;
+}
+/** The ISO start of a named slice on a date. */
+export function sliceStart(date, name) { return `${date}T${name.replace('-', ':')}:00Z`; }
+/** The cell a position falls in, by the compiler's own rule: floor of the coordinate over the cell size, in double
+ * arithmetic, printed to one decimal. The rule is reproduced exactly rather than rounded, so a position near a
+ * cell edge lands where the compiler put it. */
+export function cellOf(lon, lat) {
+    return [Number((Math.floor(lon / CELL_DEGREES) * CELL_DEGREES).toFixed(1)), Number((Math.floor(lat / CELL_DEGREES) * CELL_DEGREES).toFixed(1))];
+}
+export function cellKey(cellLon, cellLat) { return `${cellLon.toFixed(1)},${cellLat.toFixed(1)}`; }
+/** The pack part holding a vehicle: the only part, or the part whose reference list names it. */
+export function partFor(index, operatorRef, vehicleRef) {
+    const op = index.operators.find(o => o.ref === operatorRef);
+    if (!op)
+        return null;
+    if (op.parts.length === 1)
+        return op.parts[0];
+    return op.parts.find(p => p.refs?.includes(vehicleRef)) ?? null;
+}
+/** Position along a track at an instant: linear between the samples around it, null outside the track or across a
+ * gap longer than the tolerance, so a vehicle that stopped reporting does not glide. */
+export function positionAt(track, epochSeconds, maxGapSeconds = 180) {
+    if (!track.length || epochSeconds < track[0][0] || epochSeconds > track[track.length - 1][0])
+        return null;
+    let lo = 0, hi = track.length - 1;
+    while (hi - lo > 1) {
+        const mid = (lo + hi) >> 1;
+        if (track[mid][0] <= epochSeconds)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    const a = track[lo], b = track[hi];
+    if (a[0] === epochSeconds || lo === hi)
+        return [a[1], a[2]];
+    if (b[0] === epochSeconds)
+        return [b[1], b[2]];
+    if (b[0] - a[0] > maxGapSeconds)
+        return null;
+    const f = (epochSeconds - a[0]) / (b[0] - a[0]);
+    return [a[1] + (b[1] - a[1]) * f, a[2] + (b[2] - a[2]) * f];
+}
+/** The line and journey a vehicle was on at an instant, from its runs. */
+export function journeyAt(journeys, epochSeconds) {
+    let found = null;
+    for (const run of journeys) {
+        if (run[0] <= epochSeconds)
+            found = run;
+        else
+            break;
+    }
+    return found;
+}
+const platform = globalThis;
+export async function inflateGzip(bytes) {
+    if (!platform.DecompressionStream || !platform.Blob || !platform.Response)
+        throw new Error('No DecompressionStream on this platform; supply an inflater');
+    const stream = new platform.Blob([bytes]).stream().pipeThrough(new platform.DecompressionStream('gzip'));
+    return new Uint8Array(await new platform.Response(stream).arrayBuffer());
+}
+/** Packs are stored gzipped, but a server that declares the encoding hands the browser the decoded bytes; either form is accepted by its first two bytes. */
+export async function inflateIfGzipped(bytes, inflate) {
+    return bytes.length >= 2 && bytes[0] === 0x1f && bytes[1] === 0x8b ? inflate(bytes) : bytes;
+}
+function decodeText(bytes) {
+    if (!platform.TextDecoder)
+        throw new Error('No TextDecoder on this platform');
+    return new platform.TextDecoder().decode(bytes);
+}
+/** Open a published day: manifest and index up front, everything else on demand and cached per file. */
+export async function openPublishedDay(transport) {
+    const manifest = JSON.parse(await transport.text('manifest.json'));
+    const index = JSON.parse(await transport.text('index.json'));
+    if (manifest.date !== index.date)
+        throw new Error('Manifest and index disagree on the date');
+    const cache = new Map();
+    const cached = (path, load) => { let p = cache.get(path); if (!p) {
+        p = load();
+        cache.set(path, p);
+    } return p; };
+    const inflate = transport.inflate ?? inflateGzip;
+    const sliceNames = manifest.list.filter(f => f.path.startsWith('slices/')).map(f => f.path.slice(7, -5)).sort();
+    const pack = (operatorRef, vehicleRef) => { const part = partFor(index, operatorRef, vehicleRef); if (!part)
+        return Promise.reject(new Error(`No pack for ${operatorRef} ${vehicleRef}`)); return cached(part.file, async () => JSON.parse(decodeText(await inflateIfGzipped(await transport.bytes(part.file), inflate)))); };
+    return { manifest, index, sliceNames,
+        slice: name => cached(`slices/${name}.json`, async () => JSON.parse(await transport.text(`slices/${name}.json`))),
+        members: name => cached(`members/${name}.json`, async () => JSON.parse(await transport.text(`members/${name}.json`))),
+        pack,
+        vehicle: async (operatorRef, vehicleRef) => { if (!partFor(index, operatorRef, vehicleRef))
+            return null; return (await pack(operatorRef, vehicleRef)).vehicles[vehicleRef] ?? null; } };
+}
+/** A transport over fetch for a day served under a base URL. */
+export function fetchTransport(base, fetchImpl = platform.fetch) {
+    if (!fetchImpl)
+        throw new Error('No fetch on this platform; supply one');
+    const url = (path) => `${base.replace(/\/$/, '')}/${path}`;
+    const get = async (path) => { const r = await fetchImpl(url(path)); if (!r.ok)
+        throw new Error(`${path} returned HTTP ${r.status}`); return r; };
+    return { text: async (path) => (await get(path)).text(), bytes: async (path) => new Uint8Array(await (await get(path)).arrayBuffer()) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@motionstudies/core",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "private": false,
   "type": "module",
   "description": "Transport contracts and motion primitives for Motion Studies.",
@@ -190,6 +190,11 @@
       "import": "./domain/gridded-series.js",
       "default": "./domain/gridded-series.js"
     },
+    "./domain/published-day": {
+      "types": "./domain/published-day.d.ts",
+      "import": "./domain/published-day.js",
+      "default": "./domain/published-day.js"
+    },
     "./domain/field-paths": {
       "types": "./domain/field-paths.d.ts",
       "import": "./domain/field-paths.js",