monopolyline 0.0.3 → 0.0.4

package/README.md

@@ -120,3 +120,29 @@ When a schema is used or `includeTime`/`includeAccuracy` is enabled, the library
 
 For extreme data compression on massive payloads, this string output pairs perfectly with LZ-based algorithms like `lz-string` or standard `pako` (Deflate). Because Polyline outputs ASCII characters, it achieves very high Deflate ratios.
 
+
+### Merging Heterogeneous Chunks
+You can merge multiple chunks encoded with different schemas or sparse strategies into a single unified polyline string by using `mergeChunks`. It automatically uses the fast-path for chunks that match the target format and falls back to full decode/re-encode for chunks that differ.
+
+```typescript
+import { mergeChunks } from 'monopolyline';
+
+// Create chunks with different options
+const chunk1 = {
+  data: encodedString1, 
+  options: { schema: { type: 'object', fields: { lat: 'decimal', lng: 'decimal', speed: 'integer' } }, sparseStrategy: 'bitmap' }
+};
+
+const chunk2 = {
+  data: encodedString2, 
+  options: { schema: { type: 'object', fields: { lat: 'decimal', lng: 'decimal', temp: 'integer' } }, sparseStrategy: 'naive' }
+};
+
+// Target format needs to encompass both
+const targetOptions = {
+  schema: { type: 'object', fields: { lat: 'decimal', lng: 'decimal', speed: 'integer', temp: 'integer' } },
+  sparseStrategy: 'bitmap'
+};
+
+const mergedStr = mergeChunks([chunk1, chunk2], targetOptions);
+```

package/dist/index.d.ts

@@ -0,0 +1,56 @@
+export type FieldType = 'decimal' | 'integer';
+export type Schema = {
+    type: 'object';
+    fields: Record<string, FieldType>;
+} | {
+    type: 'tuple';
+    fields: FieldType[];
+};
+export declare const DEFAULT_SCHEMA: Schema;
+export declare const DEFAULT_TUPLE_SCHEMA: Schema;
+export interface Point {
+    lat: number;
+    lng: number;
+    time?: number;
+    acc?: number;
+}
+export type SparseStrategy = 'naive' | 'bitmap' | 'columnar';
+export interface EncodeOptions {
+    /**
+     * Number of decimal places for 'decimal' fields.
+     * Default: 5 (Standard Google Polyline)
+     */
+    precision?: number;
+    /**
+     * Schema definition to make encoding/decoding generic.
+     * If provided, `includeTime` and `includeAccuracy` are ignored.
+     */
+    schema?: Schema;
+    /**
+     * Include the time dimension in the encoded polyline.
+     * Default: false
+     * @deprecated Use `schema` instead for generic data structures.
+     */
+    includeTime?: boolean;
+    /**
+     * Include the accuracy dimension in the encoded polyline.
+     * Default: false
+     * @deprecated Use `schema` instead for generic data structures.
+     */
+    includeAccuracy?: boolean;
+    /**
+     * Strategy for encoding sparse data (missing values).
+     * 'naive' (default): Encodes missing values as 0 delta (repeats previous value).
+     * 'bitmap': Adds a small presence bitmask to each point to skip missing values.
+     * 'columnar': Splits the array into columns (lats, lngs, etc) with run-length presence flags.
+     */
+    sparseStrategy?: SparseStrategy;
+}
+/**
+ * Encodes an array of data into an extended polyline string.
+ */
+export declare function encode(data: any[], options?: EncodeOptions): string;
+/**
+ * Decodes an extended polyline string back into an array of data.
+ */
+export declare function decode(str: string, options?: EncodeOptions): any[];

package/dist/index.js

@@ -0,0 +1,473 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TUPLE_SCHEMA = exports.DEFAULT_SCHEMA = void 0;
+exports.encode = encode;
+exports.decode = decode;
+exports.DEFAULT_SCHEMA = {
+    type: 'object',
+    fields: {
+        lat: 'decimal',
+        lng: 'decimal'
+    }
+};
+exports.DEFAULT_TUPLE_SCHEMA = {
+    type: 'tuple',
+    fields: ['decimal', 'decimal']
+};
+/**
+ * Encodes a numeric value using ZigZag encoding and base64-like chunking.
+ */
+function encodeNumber(value) {
+    let zz = value < 0 ? -value * 2 - 1 : value * 2;
+    let str = "";
+    while (zz >= 0x20) {
+        str += String.fromCharCode((0x20 | (zz & 0x1f)) + 63);
+        zz = Math.floor(zz / 32);
+    }
+    str += String.fromCharCode(zz + 63);
+    return str;
+}
+/**
+ * Decodes a single numeric value from the encoded string starting at the given index.
+ */
+function decodeNumber(str, index) {
+    let b = 0;
+    let result = 0;
+    let factor = 1;
+    do {
+        if (index >= str.length) {
+            throw new Error("Invalid polyline string: unexpected end of string");
+        }
+        b = str.charCodeAt(index++) - 63;
+        result += (b & 0x1f) * factor;
+        factor *= 32;
+    } while (b >= 0x20);
+    const value = result % 2 === 1 ? -(Math.floor(result / 2) + 1) : Math.floor(result / 2);
+    return [value, index];
+}
+/**
+ * Encodes an array of data into an extended polyline string.
+ */
+function encode(data, options = {}) {
+    if (!options.schema) {
+        return encodeLegacy(data, options);
+    }
+    return encodeGeneric(data, options);
+}
+/**
+ * Decodes an extended polyline string back into an array of data.
+ */
+function decode(str, options = {}) {
+    if (!options.schema) {
+        return decodeLegacy(str, options);
+    }
+    return decodeGeneric(str, options);
+}
+function encodeGeneric(data, options) {
+    var _a, _b;
+    const precision = (_a = options.precision) !== null && _a !== void 0 ? _a : 5;
+    const factor = Math.pow(10, precision);
+    const sparseStrategy = (_b = options.sparseStrategy) !== null && _b !== void 0 ? _b : 'naive';
+    const schema = options.schema;
+    const schemaFields = [];
+    if (schema.type === 'object') {
+        for (const key of Object.keys(schema.fields)) {
+            schemaFields.push({ key, type: schema.fields[key] });
+        }
+    }
+    else {
+        for (let i = 0; i < schema.fields.length; i++) {
+            schemaFields.push({ key: i, type: schema.fields[i] });
+        }
+    }
+    let result = "";
+    if (sparseStrategy === 'columnar') {
+        result += encodeNumber(data.length);
+        for (let i = 0; i < schemaFields.length; i++) {
+            const field = schemaFields[i];
+            let prev = 0;
+            let presence = 0;
+            let bitIndex = 0;
+            let presenceStrs = "";
+            let dataStrs = "";
+            for (const pt of data) {
+                const val = pt[field.key];
+                if (val != null) {
+                    presence |= (1 << bitIndex);
+                    const scaled = field.type === 'decimal' ? Math.round(val * factor) : Math.round(val);
+                    dataStrs += encodeNumber(scaled - prev);
+                    prev = scaled;
+                }
+                bitIndex++;
+                if (bitIndex === 30) {
+                    presenceStrs += encodeNumber(presence);
+                    presence = 0;
+                    bitIndex = 0;
+                }
+            }
+            if (bitIndex > 0)
+                presenceStrs += encodeNumber(presence);
+            result += presenceStrs + dataStrs;
+        }
+        return result;
+    }
+    // naive or bitmap
+    const prevs = new Array(schemaFields.length).fill(0);
+    for (const pt of data) {
+        if (sparseStrategy === 'bitmap') {
+            let bitmask = 0;
+            for (let i = 0; i < schemaFields.length; i++) {
+                if (pt[schemaFields[i].key] != null)
+                    bitmask |= (1 << i);
+            }
+            result += encodeNumber(bitmask);
+        }
+        for (let i = 0; i < schemaFields.length; i++) {
+            const field = schemaFields[i];
+            const val = pt[field.key];
+            if (sparseStrategy === 'bitmap') {
+                if (val != null) {
+                    const scaled = field.type === 'decimal' ? Math.round(val * factor) : Math.round(val);
+                    result += encodeNumber(scaled - prevs[i]);
+                    prevs[i] = scaled;
+                }
+            }
+            else {
+                // naive
+                if (val != null) {
+                    const scaled = field.type === 'decimal' ? Math.round(val * factor) : Math.round(val);
+                    result += encodeNumber(scaled - prevs[i]);
+                    prevs[i] = scaled;
+                }
+                else {
+                    result += encodeNumber(0);
+                }
+            }
+        }
+    }
+    return result;
+}
+function decodeGeneric(str, options) {
+    var _a, _b;
+    const precision = (_a = options.precision) !== null && _a !== void 0 ? _a : 5;
+    const factor = Math.pow(10, precision);
+    const sparseStrategy = (_b = options.sparseStrategy) !== null && _b !== void 0 ? _b : 'naive';
+    const schema = options.schema;
+    const schemaFields = [];
+    if (schema.type === 'object') {
+        for (const key of Object.keys(schema.fields)) {
+            schemaFields.push({ key, type: schema.fields[key] });
+        }
+    }
+    else {
+        for (let i = 0; i < schema.fields.length; i++) {
+            schemaFields.push({ key: i, type: schema.fields[i] });
+        }
+    }
+    let index = 0;
+    if (sparseStrategy === 'columnar') {
+        if (str.length === 0)
+            return [];
+        let ptCount = 0;
+        [ptCount, index] = decodeNumber(str, index);
+        const results = Array.from({ length: ptCount }, () => (schema.type === 'tuple' ? [] : {}));
+        for (let f = 0; f < schemaFields.length; f++) {
+            const field = schemaFields[f];
+            const presenceFlags = [];
+            const numPresenceInts = Math.ceil(ptCount / 30);
+            for (let i = 0; i < numPresenceInts; i++) {
+                let p = 0;
+                [p, index] = decodeNumber(str, index);
+                for (let b = 0; b < 30 && (i * 30 + b) < ptCount; b++) {
+                    presenceFlags.push((p & (1 << b)) !== 0);
+                }
+            }
+            let prev = 0;
+            for (let i = 0; i < ptCount; i++) {
+                if (presenceFlags[i]) {
+                    let delta = 0;
+                    [delta, index] = decodeNumber(str, index);
+                    prev += delta;
+                    const val = field.type === 'decimal' ? prev / factor : prev;
+                    results[i][field.key] = val;
+                }
+            }
+        }
+        return results;
+    }
+    const prevs = new Array(schemaFields.length).fill(0);
+    const results = [];
+    while (index < str.length) {
+        let bitmask = (1 << schemaFields.length) - 1; // default all present
+        if (sparseStrategy === 'bitmap') {
+            [bitmask, index] = decodeNumber(str, index);
+        }
+        const pt = schema.type === 'tuple' ? [] : {};
+        for (let f = 0; f < schemaFields.length; f++) {
+            const field = schemaFields[f];
+            if (sparseStrategy === 'bitmap') {
+                if ((bitmask & (1 << f)) !== 0) {
+                    let delta = 0;
+                    [delta, index] = decodeNumber(str, index);
+                    prevs[f] += delta;
+                    pt[field.key] = field.type === 'decimal' ? prevs[f] / factor : prevs[f];
+                }
+            }
+            else {
+                // naive
+                let delta = 0;
+                [delta, index] = decodeNumber(str, index);
+                prevs[f] += delta;
+                pt[field.key] = field.type === 'decimal' ? prevs[f] / factor : prevs[f];
+            }
+        }
+        results.push(pt);
+    }
+    return results;
+}
+function encodeLegacy(points, options) {
+    var _a, _b, _c, _d;
+    const precision = (_a = options.precision) !== null && _a !== void 0 ? _a : 5;
+    const factor = Math.pow(10, precision);
+    const includeTime = (_b = options.includeTime) !== null && _b !== void 0 ? _b : false;
+    const includeAccuracy = (_c = options.includeAccuracy) !== null && _c !== void 0 ? _c : false;
+    const sparseStrategy = (_d = options.sparseStrategy) !== null && _d !== void 0 ? _d : 'naive';
+    let result = "";
+    if (sparseStrategy === 'columnar') {
+        result += encodeNumber(points.length);
+        let prevLat = 0, prevLng = 0;
+        for (const point of points) {
+            const lat = Math.round(point.lat * factor);
+            const lng = Math.round(point.lng * factor);
+            result += encodeNumber(lat - prevLat);
+            result += encodeNumber(lng - prevLng);
+            prevLat = lat;
+            prevLng = lng;
+        }
+        if (includeTime) {
+            let prevTime = 0;
+            let timePresence = 0;
+            let bitIndex = 0;
+            let presenceStrs = "";
+            let dataStrs = "";
+            for (const point of points) {
+                if (point.time != null) {
+                    timePresence |= (1 << bitIndex);
+                    const time = Math.round(point.time);
+                    dataStrs += encodeNumber(time - prevTime);
+                    prevTime = time;
+                }
+                bitIndex++;
+                if (bitIndex === 30) {
+                    presenceStrs += encodeNumber(timePresence);
+                    timePresence = 0;
+                    bitIndex = 0;
+                }
+            }
+            if (bitIndex > 0)
+                presenceStrs += encodeNumber(timePresence);
+            result += presenceStrs + dataStrs;
+        }
+        if (includeAccuracy) {
+            let prevAcc = 0;
+            let accPresence = 0;
+            let bitIndex = 0;
+            let presenceStrs = "";
+            let dataStrs = "";
+            for (const point of points) {
+                if (point.acc != null) {
+                    accPresence |= (1 << bitIndex);
+                    const acc = Math.round(point.acc);
+                    dataStrs += encodeNumber(acc - prevAcc);
+                    prevAcc = acc;
+                }
+                bitIndex++;
+                if (bitIndex === 30) {
+                    presenceStrs += encodeNumber(accPresence);
+                    accPresence = 0;
+                    bitIndex = 0;
+                }
+            }
+            if (bitIndex > 0)
+                presenceStrs += encodeNumber(accPresence);
+            result += presenceStrs + dataStrs;
+        }
+        return result;
+    }
+    let prevLat = 0;
+    let prevLng = 0;
+    let prevTime = 0;
+    let prevAcc = 0;
+    for (const point of points) {
+        const lat = Math.round(point.lat * factor);
+        const lng = Math.round(point.lng * factor);
+        if (sparseStrategy === 'bitmap' && (includeTime || includeAccuracy)) {
+            let bitmask = 0;
+            if (includeTime && point.time != null)
+                bitmask |= 1;
+            if (includeAccuracy && point.acc != null)
+                bitmask |= 2;
+            result += encodeNumber(bitmask);
+        }
+        result += encodeNumber(lat - prevLat);
+        result += encodeNumber(lng - prevLng);
+        prevLat = lat;
+        prevLng = lng;
+        if (sparseStrategy === 'bitmap') {
+            if (includeTime && point.time != null) {
+                const time = Math.round(point.time);
+                result += encodeNumber(time - prevTime);
+                prevTime = time;
+            }
+            if (includeAccuracy && point.acc != null) {
+                const acc = Math.round(point.acc);
+                result += encodeNumber(acc - prevAcc);
+                prevAcc = acc;
+            }
+        }
+        else {
+            if (includeTime) {
+                if (point.time != null) {
+                    const time = Math.round(point.time);
+                    result += encodeNumber(time - prevTime);
+                    prevTime = time;
+                }
+                else {
+                    result += encodeNumber(0);
+                }
+            }
+            if (includeAccuracy) {
+                if (point.acc != null) {
+                    const acc = Math.round(point.acc);
+                    result += encodeNumber(acc - prevAcc);
+                    prevAcc = acc;
+                }
+                else {
+                    result += encodeNumber(0);
+                }
+            }
+        }
+    }
+    return result;
+}
+function decodeLegacy(str, options) {
+    var _a, _b, _c, _d;
+    const precision = (_a = options.precision) !== null && _a !== void 0 ? _a : 5;
+    const factor = Math.pow(10, precision);
+    const includeTime = (_b = options.includeTime) !== null && _b !== void 0 ? _b : false;
+    const includeAccuracy = (_c = options.includeAccuracy) !== null && _c !== void 0 ? _c : false;
+    const sparseStrategy = (_d = options.sparseStrategy) !== null && _d !== void 0 ? _d : 'naive';
+    let index = 0;
+    const points = [];
+    if (sparseStrategy === 'columnar') {
+        if (str.length === 0)
+            return points;
+        let ptCount = 0;
+        [ptCount, index] = decodeNumber(str, index);
+        let prevLat = 0;
+        let prevLng = 0;
+        for (let i = 0; i < ptCount; i++) {
+            let dLat = 0, dLng = 0;
+            [dLat, index] = decodeNumber(str, index);
+            [dLng, index] = decodeNumber(str, index);
+            prevLat += dLat;
+            prevLng += dLng;
+            points.push({ lat: prevLat / factor, lng: prevLng / factor });
+        }
+        if (includeTime) {
+            const presenceFlags = [];
+            const numPresenceInts = Math.ceil(ptCount / 30);
+            for (let i = 0; i < numPresenceInts; i++) {
+                let p = 0;
+                [p, index] = decodeNumber(str, index);
+                for (let b = 0; b < 30 && (i * 30 + b) < ptCount; b++) {
+                    presenceFlags.push((p & (1 << b)) !== 0);
+                }
+            }
+            let prevTime = 0;
+            for (let i = 0; i < ptCount; i++) {
+                if (presenceFlags[i]) {
+                    let dTime = 0;
+                    [dTime, index] = decodeNumber(str, index);
+                    prevTime += dTime;
+                    points[i].time = prevTime;
+                }
+            }
+        }
+        if (includeAccuracy) {
+            const presenceFlags = [];
+            const numPresenceInts = Math.ceil(ptCount / 30);
+            for (let i = 0; i < numPresenceInts; i++) {
+                let p = 0;
+                [p, index] = decodeNumber(str, index);
+                for (let b = 0; b < 30 && (i * 30 + b) < ptCount; b++) {
+                    presenceFlags.push((p & (1 << b)) !== 0);
+                }
+            }
+            let prevAcc = 0;
+            for (let i = 0; i < ptCount; i++) {
+                if (presenceFlags[i]) {
+                    let dAcc = 0;
+                    [dAcc, index] = decodeNumber(str, index);
+                    prevAcc += dAcc;
+                    points[i].acc = prevAcc;
+                }
+            }
+        }
+        return points;
+    }
+    let prevLat = 0;
+    let prevLng = 0;
+    let prevTime = 0;
+    let prevAcc = 0;
+    while (index < str.length) {
+        let bitmask = 3;
+        if (sparseStrategy === 'bitmap' && (includeTime || includeAccuracy)) {
+            [bitmask, index] = decodeNumber(str, index);
+        }
+        let dLat = 0;
+        let dLng = 0;
+        [dLat, index] = decodeNumber(str, index);
+        [dLng, index] = decodeNumber(str, index);
+        prevLat += dLat;
+        prevLng += dLng;
+        const point = {
+            lat: prevLat / factor,
+            lng: prevLng / factor,
+        };
+        if (sparseStrategy === 'bitmap') {
+            if (includeTime && (bitmask & 1)) {
+                let dTime = 0;
+                [dTime, index] = decodeNumber(str, index);
+                prevTime += dTime;
+                point.time = prevTime;
+            }
+            if (includeAccuracy && (bitmask & 2)) {
+                let dAcc = 0;
+                [dAcc, index] = decodeNumber(str, index);
+                prevAcc += dAcc;
+                point.acc = prevAcc;
+            }
+        }
+        else {
+            if (includeTime) {
+                let dTime = 0;
+                [dTime, index] = decodeNumber(str, index);
+                if (dTime !== 0) {
+                    prevTime += dTime;
+                    point.time = prevTime;
+                }
+            }
+            if (includeAccuracy) {
+                let dAcc = 0;
+                [dAcc, index] = decodeNumber(str, index);
+                if (dAcc !== 0) {
+                    prevAcc += dAcc;
+                    point.acc = prevAcc;
+                }
+            }
+        }
+        points.push(point);
+    }
+    return points;
+}

package/index.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'bun:test';
-import { encode, decode, EncodeOptions, Schema } from './index';
+import { encode, decode, merge, mergeMany, mergeChunks, EncodeOptions, Schema } from './index';
 
 describe('monopolyline backwards compatibility', () => {
   it('encodes and decodes lat/lng successfully (naive)', () => {
@@ -140,3 +140,142 @@ describe('monopolyline generic schema', () => {
     expect(decoded[2][3]).toBeUndefined();
   });
 });
+
+describe('monopolyline merge', () => {
+  it('merges naive polylines correctly', () => {
+    const pointsA = [{ lat: 38.5, lng: -120.2 }, { lat: 40.7, lng: -120.95 }];
+    const pointsB = [{ lat: 43.252, lng: -126.453 }, { lat: 44.0, lng: -127.0 }];
+    const encodedA = encode(pointsA);
+    const encodedB = encode(pointsB);
+    const merged = merge(encodedA, encodedB);
+    const decoded = decode(merged);
+    
+    expect(decoded.length).toBe(4);
+    expect(decoded[1].lat).toBeCloseTo(40.7, 5);
+    expect(decoded[2].lat).toBeCloseTo(43.252, 5);
+    expect(decoded[3].lat).toBeCloseTo(44.0, 5);
+  });
+
+  it('merges bitmap sparse polylines correctly', () => {
+    const dataA = [
+      { lat: 38.5, lng: -120.2, speed: 50 },
+      { lat: 40.7, lng: -120.95 }
+    ];
+    const dataB = [
+      { lat: 43.2, lng: -126.4, speed: 60 },
+      { lat: 44.0, lng: -127.0 }
+    ];
+    
+    const opts: EncodeOptions = {
+      schema: {
+        type: 'object',
+        fields: {
+          lat: 'decimal',
+          lng: 'decimal',
+          speed: 'integer'
+        }
+      },
+      sparseStrategy: 'bitmap'
+    };
+    
+    const encodedA = encode(dataA, opts);
+    const encodedB = encode(dataB, opts);
+    const merged = merge(encodedA, encodedB, opts);
+    const decoded = decode(merged, opts);
+    
+    expect(decoded.length).toBe(4);
+    expect(decoded[0].speed).toBe(50);
+    expect(decoded[1].speed).toBeUndefined();
+    expect(decoded[2].speed).toBe(60);
+    expect(decoded[3].speed).toBeUndefined();
+  });
+  
+  it('merges columnar sparse polylines correctly', () => {
+    const dataA = [
+      { lat: 38.5, lng: -120.2, speed: 50 },
+      { lat: 40.7, lng: -120.95 }
+    ];
+    const dataB = [
+      { lat: 43.2, lng: -126.4, speed: 60 },
+      { lat: 44.0, lng: -127.0 }
+    ];
+    
+    const opts: EncodeOptions = {
+      schema: {
+        type: 'object',
+        fields: {
+          lat: 'decimal',
+          lng: 'decimal',
+          speed: 'integer'
+        }
+      },
+      sparseStrategy: 'columnar'
+    };
+    
+    const encodedA = encode(dataA, opts);
+    const encodedB = encode(dataB, opts);
+    
+    // Suppress warning for testing
+    const merged = merge(encodedA, encodedB, { ...opts, suppressWarnings: true });
+    const decoded = decode(merged, opts);
+    
+    expect(decoded.length).toBe(4);
+    expect(decoded[0].speed).toBe(50);
+    expect(decoded[1].speed).toBeUndefined();
+    expect(decoded[2].speed).toBe(60);
+    expect(decoded[3].speed).toBeUndefined();
+  });
+});
+
+describe('monopolyline mergeChunks', () => {
+  it('merges heterogeneous chunks correctly', () => {
+    // Chunk 1: bitmap sparse, has speed
+    const dataA = [
+      { lat: 38.5, lng: -120.2, speed: 50 },
+      { lat: 40.7, lng: -120.95 }
+    ];
+    const optsA: EncodeOptions = {
+      schema: { type: 'object', fields: { lat: 'decimal', lng: 'decimal', speed: 'integer' } },
+      sparseStrategy: 'bitmap'
+    };
+    const encodedA = encode(dataA, optsA);
+
+    // Chunk 2: naive, has heading instead of speed
+    const dataB = [
+      { lat: 43.2, lng: -126.4, heading: 90 },
+      { lat: 44.0, lng: -127.0, heading: 180 }
+    ];
+    const optsB: EncodeOptions = {
+      schema: { type: 'object', fields: { lat: 'decimal', lng: 'decimal', heading: 'integer' } },
+      sparseStrategy: 'naive'
+    };
+    const encodedB = encode(dataB, optsB);
+
+    // Target format: needs speed and heading, bitmap
+    const targetOpts: EncodeOptions = {
+      schema: { type: 'object', fields: { lat: 'decimal', lng: 'decimal', speed: 'integer', heading: 'integer' } },
+      sparseStrategy: 'bitmap'
+    };
+
+    const chunks = [
+      { data: encodedA, options: optsA },
+      { data: encodedB, options: optsB }
+    ];
+
+    const merged = mergeChunks(chunks, targetOpts);
+    const decoded = decode(merged, targetOpts);
+
+    expect(decoded.length).toBe(4);
+    expect(decoded[0].speed).toBe(50);
+    expect(decoded[0].heading).toBeUndefined();
+    expect(decoded[1].speed).toBeUndefined();
+    
+    expect(decoded[2].speed).toBeUndefined();
+    expect(decoded[2].heading).toBe(90);
+    expect(decoded[3].heading).toBe(180);
+    
+    // Check points
+    expect(decoded[1].lat).toBeCloseTo(40.7, 5);
+    expect(decoded[2].lat).toBeCloseTo(43.2, 5);
+  });
+});

package/index.ts

@@ -26,6 +26,10 @@ export interface Point {
 
 export type SparseStrategy = 'naive' | 'bitmap' | 'columnar';
 
+export interface EncodeState {
+  values: number[];
+}
+
 export interface EncodeOptions {
   /**
    * Number of decimal places for 'decimal' fields.
@@ -60,6 +64,31 @@ export interface EncodeOptions {
    * 'columnar': Splits the array into columns (lats, lngs, etc) with run-length presence flags.
    */
   sparseStrategy?: SparseStrategy;
+
+  /**
+   * Internal state used for merging polylines.
+   */
+  initialState?: EncodeState;
+}
+
+export interface MergeOptions extends Omit<EncodeOptions, 'initialState'> {
+  /**
+   * Suppress warnings when merging 'columnar' sparseStrategy.
+   */
+  suppressWarnings?: boolean;
+}
+
+export interface EncodedChunk {
+  /**
+   * The encoded polyline string for this chunk.
+   */
+  data: string;
+  
+  /**
+   * The encoding options used for this specific chunk.
+   * If omitted, it is assumed to match the targetOptions of the merge.
+   */
+  options?: EncodeOptions;
 }
 
 /**
@@ -168,7 +197,7 @@ function encodeGeneric(data: any[], options: EncodeOptions): string {
   }
 
   // naive or bitmap
-  const prevs = new Array(schemaFields.length).fill(0);
+  const prevs = options.initialState?.values ? [...options.initialState.values] : new Array(schemaFields.length).fill(0);
   
   for (const pt of data) {
     if (sparseStrategy === 'bitmap') {
@@ -364,10 +393,10 @@ function encodeLegacy(points: Point[], options: EncodeOptions): string {
     return result;
   }
 
-  let prevLat = 0;
-  let prevLng = 0;
-  let prevTime = 0;
-  let prevAcc = 0;
+  let prevLat = options.initialState?.values[0] ?? 0;
+  let prevLng = options.initialState?.values[1] ?? 0;
+  let prevTime = options.initialState?.values[2] ?? 0;
+  let prevAcc = options.initialState?.values[3] ?? 0;
 
   for (const point of points) {
     const lat = Math.round(point.lat * factor);
@@ -553,3 +582,181 @@ function decodeLegacy(str: string, options: EncodeOptions): Point[] {
   return points;
 }
 
+export function getFinalState(str: string, options: EncodeOptions = {}): EncodeState {
+  const precision = options.precision ?? 5;
+  const sparseStrategy = options.sparseStrategy ?? 'naive';
+  
+  if (str.length === 0 || sparseStrategy === 'columnar') {
+    return { values: [] };
+  }
+
+  let index = 0;
+  
+  if (options.schema) {
+    const schema = options.schema;
+    const numFields = schema.type === 'object' ? Object.keys(schema.fields).length : schema.fields.length;
+    const prevs = new Array(numFields).fill(0);
+    
+    while (index < str.length) {
+      let bitmask = (1 << numFields) - 1;
+      if (sparseStrategy === 'bitmap') {
+        [bitmask, index] = decodeNumber(str, index);
+      }
+      
+      for (let f = 0; f < numFields; f++) {
+        if (sparseStrategy === 'bitmap') {
+          if ((bitmask & (1 << f)) !== 0) {
+            let delta = 0;
+            [delta, index] = decodeNumber(str, index);
+            prevs[f] += delta;
+          }
+        } else {
+          let delta = 0;
+          [delta, index] = decodeNumber(str, index);
+          prevs[f] += delta;
+        }
+      }
+    }
+    return { values: prevs };
+  } else {
+    const includeTime = options.includeTime ?? false;
+    const includeAccuracy = options.includeAccuracy ?? false;
+    let prevLat = 0, prevLng = 0, prevTime = 0, prevAcc = 0;
+
+    while (index < str.length) {
+      let bitmask = 3;
+      if (sparseStrategy === 'bitmap' && (includeTime || includeAccuracy)) {
+        [bitmask, index] = decodeNumber(str, index);
+      }
+
+      let dLat = 0, dLng = 0;
+      [dLat, index] = decodeNumber(str, index);
+      [dLng, index] = decodeNumber(str, index);
+      prevLat += dLat;
+      prevLng += dLng;
+
+      if (sparseStrategy === 'bitmap') {
+        if (includeTime && (bitmask & 1)) {
+          let dTime = 0;
+          [dTime, index] = decodeNumber(str, index);
+          prevTime += dTime;
+        }
+        if (includeAccuracy && (bitmask & 2)) {
+          let dAcc = 0;
+          [dAcc, index] = decodeNumber(str, index);
+          prevAcc += dAcc;
+        }
+      } else {
+        if (includeTime) {
+          let dTime = 0;
+          [dTime, index] = decodeNumber(str, index);
+          if (dTime !== 0) prevTime += dTime;
+        }
+        if (includeAccuracy) {
+          let dAcc = 0;
+          [dAcc, index] = decodeNumber(str, index);
+          if (dAcc !== 0) prevAcc += dAcc;
+        }
+      }
+    }
+    return { values: [prevLat, prevLng, prevTime, prevAcc] };
+  }
+}
+
+export function merge(encodedA: string, encodedB: string, options: MergeOptions = {}): string {
+  return mergeMany([encodedA, encodedB], options);
+}
+
+export function mergeMany(encodedList: string[], options: MergeOptions = {}): string {
+  const list = encodedList.filter(s => s.length > 0);
+  if (list.length === 0) return "";
+  if (list.length === 1) return list[0];
+
+  const sparseStrategy = options.sparseStrategy ?? 'naive';
+
+  if (sparseStrategy === 'columnar') {
+    if (!options.suppressWarnings) {
+      console.warn("Merging 'columnar' encoded strings requires a full decode and re-encode. Pass { suppressWarnings: true } to suppress this warning.");
+    }
+    // Full decode and encode
+    const allPoints: any[] = [];
+    for (const str of list) {
+      const decoded = decode(str, options);
+      allPoints.push(...decoded);
+    }
+    return encode(allPoints, options);
+  }
+
+  // Naive or Bitmap: fast path merging
+  let result = list[0];
+  let currentState = getFinalState(result, options);
+
+  for (let i = 1; i < list.length; i++) {
+    const strB = list[i];
+    const pointsB = decode(strB, options);
+    
+    const encodeOpts: EncodeOptions = {
+      ...options,
+      initialState: currentState
+    };
+    
+    const encodedB = encode(pointsB, encodeOpts);
+    result += encodedB;
+    
+    // Update state for the next merge
+    currentState = getFinalState(encodedB, encodeOpts);
+  }
+
+  return result;
+}
+
+export function mergeChunks(chunks: EncodedChunk[], targetOptions: MergeOptions = {}): string {
+  const list = chunks.filter(c => c.data.length > 0);
+  if (list.length === 0) return "";
+
+  const targetStrategy = targetOptions.sparseStrategy ?? 'naive';
+
+  if (targetStrategy === 'columnar') {
+    if (!targetOptions.suppressWarnings) {
+      console.warn("Merging into 'columnar' requires full decode and re-encode. Pass { suppressWarnings: true } to suppress this warning.");
+    }
+    const allPoints: any[] = [];
+    for (const chunk of list) {
+      const decoded = decode(chunk.data, chunk.options ?? targetOptions);
+      allPoints.push(...decoded);
+    }
+    return encode(allPoints, targetOptions);
+  }
+
+  let result = "";
+  let currentState: EncodeState | undefined = undefined;
+
+  for (let i = 0; i < list.length; i++) {
+    const chunk = list[i];
+    // If chunk options are provided, use them; otherwise assume it matches target options
+    const chunkOpts = chunk.options ?? targetOptions;
+    const isTargetFormat = !chunk.options; // If omitted, we assume it's already target format
+
+    if (i === 0 && isTargetFormat) {
+      // Fast-path for the very first chunk: if it's already in the target format, append as-is
+      result = chunk.data;
+      currentState = getFinalState(result, targetOptions);
+    } else {
+      // Decode the chunk using its specific options
+      const decodedPoints = decode(chunk.data, chunkOpts);
+      
+      // Re-encode into the target format, applying the offset from the current state
+      const reencodeOpts: EncodeOptions = {
+        ...targetOptions,
+        initialState: currentState
+      };
+      
+      const encodedChunk = encode(decodedPoints, reencodeOpts);
+      result += encodedChunk;
+      
+      currentState = getFinalState(encodedChunk, reencodeOpts);
+    }
+  }
+
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "monopolyline",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "An extended Google Polyline encoder/decoder supporting timestamps, accuracy, and sparse data strategies.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,4 +20,4 @@
     "typescript": "^5.0.0",
     "bun-types": "latest"
   }
-}
+}