Add typing information #7

qwertie · 2024-01-26T22:20:34Z

I found that there's no @types/shp-to-geojson module, so I prepared a types file myself (below).

I think there's a bug: I inferred that summary.crs (which reports the entire contents of the .prj file; why is it called crs?) sometimes has a type of string, and sometimes Buffer. It's a string if it is downloaded from a remote URL in options.remotePath, but if it is assigned via options.arraybuffers.projString then it is converted from string to Buffer.

Surprisingly, I discovered that I could not import the Buffer from 'node:buffer' because doing so somehow causes TypeScript to ignore the types file completely. Therefore, my version contains a lame attempt to redefine Buffer by hand.

Finally, I was unable to use shp-to-geojson in browser by importing shp-to-geojson, because this imports the node.js version. Therefore I import shp-to-geojson/dist/shp-to-geojson.browser instead, but this means I need type information specifically for that file. That's why the definition of class Shp is repeated twice. (There's also a shp-to-geojson.browser.min.js of course, but I'm assuming Webpack will minify it for me in production, so I should only need to import the non-minified version).

declare module 'shp-to-geojson' {
    export type ShpGeometryType = 
        | 'Point' | 'PointZ' | 'PointM'
        | 'PolyLine' | 'PolyLineZ' | 'PolyLineM'
        | 'Polygon' | 'PolygonZ' | 'PolygonM'
        | 'MultiPoint' | 'MultiPointZ' | 'MultiPointM';

    type WithImplicitCoercion<T> = T | { valueOf(): T; };
    type ConvertibleToBuffer = 
        | WithImplicitCoercion<ArrayBuffer | SharedArrayBuffer | string | Uint8Array | readonly number[]> 
        | { [Symbol.toPrimitive](hint: 'string'): string; };

    type Buffer = Uint8Array & {
        parent: any, offset: number, compare: any, includes: any, indexOf: any,
        lastIndexOf: any, write: any, toJSON: any, slice: any, copy: any, fill: any,
        readUintLE: any, readUIntLE: any, readUintBE: any, readUIntBE: any,
        readUint8: any, readUInt8, readUint16LE: any, readUInt16LE: any,
        readUint16BE: any, readUInt16BE: any, readUint32LE: any, readUInt32LE: any,
        readUint32BE: any, readUInt32BE: any, readBigUInt64LE: any, readBigUInt64BE: any,
        readIntLE: any, readIntBE: any, readInt8: any, readInt16LE: any, 
        readInt16BE: any, readInt32LE: any, readInt32BE: any, readBigInt64LE: any, 
        readBigInt64BE: any, readFloatLE: any, readFloatBE: any, readDoubleLE: any, 
        readDoubleBE: any,
        writeUIntLE: any, writeUIntBE: any, writeUInt8: any, writeUInt16LE: any, 
        writeUInt16BE: any, writeUInt32LE: any, writeUInt32BE: any, writeBigUInt64LE: any, 
        writeBigUInt64BE: any, writeIntLE: any, writeIntBE: any, writeInt8: any, 
        writeInt16LE: any, writeInt16BE: any, writeInt32LE: any, writeInt32BE: any, 
        writeBigInt64LE: any, writeBigInt64BE: any, writeFloatLE: any, writeFloatBE: any, 
        writeDoubleLE: any, writeDoubleBE: any, 
    };

    export interface ShpOptions {
        arraybuffers?: {
            shpBuffer: ConvertibleToBuffer;
            dbfBuffer?: ConvertibleToBuffer|null;
            projString?: ConvertibleToBuffer|null; // not expected to be a string, apparently
        }
        remotePath?: string;
        filePath?: string; // filePath is not a valid option in the browser
        filePathZipped?: string; // filePathZipped is not a valid option in the browser
    }

    export interface Summary {
        shpGeometryType: ShpGeometryType,
        /** This is the number in bytes 4-7 of the file header, which are unused 
         *  according to the ESRI Shapefile Technical Description[1]. This number is
         *  not used to read the file; instead, this class reads until EOF.
         *  [1] https://www.esri.com/content/dam/esrisites/sitecore-archive/Files/Pdfs/library/whitepapers/pdfs/shapefile.pdf
         **/
        numberOfFeatures: number,
        /** Bounding box stored in the Shapefile's header (Z and M ranges 
         *  are not included) */
        bbox: [number, number, number, number],
        /** Contents of the .prj file */
        crs: Buffer|string|null,
    }
    
    /** A class for decoding shapefiles into GeoJSON format. Does not support "M" Shapefiles 
     *  (PointM, PolyLineM, PolygonM). */
    export default class Shp {
        constructor(options: ShpOptions);
        /** Downloads from options.remotePath, if applicable */
        load(): Promise<void>;
        /** Decodes shapefile contents into GeoJSON.FeatureCollection */
        getGeoJson(): GeoJSON.FeatureCollection & { bbox: [number, number, number, number] };
        *streamGeoJsonFeatures(): Generator<GeoJSON.Feature, void, unknown>;

        readonly loaded: boolean;
        readonly summary: Summary;

        // readonly _shpBuffer?: Buffer|null;
        // readonly _tableBuffer?: Buffer|null;
        // readonly _projString?: Buffer|null;
        // readonly _properties?: { getRowProperties(index): { [k:string]: number|string } };
        // readonly _bbox: [number, number, number, number];
        // readonly _numberOfFeatures: number;
        // readonly _shpGeometryType: ShpGeometryType|null;
        // readonly _init(): void;
    }
}

declare module 'shp-to-geojson/dist/shp-to-geojson.browser.min.js' {
    /** A class for decoding shapefiles into GeoJSON format. Does not support "M" Shapefiles 
     *  (PointM, PolyLineM, PolygonM). */
    export default class Shp {
        constructor(options: ShpOptions);
        /** Downloads from options.remotePath, if applicable */
        load(): Promise<void>;
        /** Decodes shapefile contents into GeoJSON.FeatureCollection */
        getGeoJson(): GeoJSON.FeatureCollection & { bbox: [number, number, number, number] };
        *streamGeoJsonFeatures(): Generator<GeoJSON.Feature, void, unknown>;

        readonly loaded: boolean;
        readonly summary: Summary;
    }
}

The text was updated successfully, but these errors were encountered:

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add typing information #7

Add typing information #7

Add typing information #7

Add typing information #7

Comments

Uh oh!