fgb-vt - v1.0.6
    Preparing search index...

    Class S3Connector

    S3 connector using AWS SDK v3 (@aws-sdk/client-s3).

    The SDK is a peer dependency -- it is only required at runtime if this connector is instantiated. Byte-range reads use GetObject with an HTTP Range header, identical to how the AWS CLI performs partial downloads.

    The S3 client is created lazily on the first read and reused for all subsequent requests. Call S3Connector.close to destroy the client and release its underlying HTTP connection pool.

    import { S3Connector } from '@geozelot/fgb-vt';

    const connector = new S3Connector({
      region: 'us-east-1',
      maxConcurrency: 8,
    });

    const bytes = await connector.read(
      's3://my-bucket/tiles/buildings.fgb',
      0,
      1024,
    );

    await connector.close();

    import * as s3 from '@aws-sdk/client-s3';

    const connector = new S3Connector({ client: new s3.S3Client({}), sdk: s3 });

    const minio = new S3Connector({
      region: 'us-east-1',
      endpoint: 'http://localhost:9000',
      forcePathStyle: true,
      credentials: {
        accessKeyId: 'minioadmin',
        secretAccessKey: 'minioadmin',
      },
    });

    Implements

    Index
    constructor
    cacheNamespace? hints
    close read readHead readRanges
    cacheNamespace?: string

    Optional: identifies the storage this connector reads, so cached headers and index pages are shared only between connectors that resolve a path to the same file.

    Connectors with equal namespaces must map equal paths to the same resource. Without a namespace, cache entries are private to the connector instance (and a persistent cache cannot be reused by another process). The built-in connectors set local, http and s3:<endpoint>.

    hints: ConnectorHints

    Optional tuning hints for the pipeline.

    • Destroy the underlying S3Client and release its HTTP connection pool.

      After calling this method, the connector must not be used for further reads. Calling close() on an already-closed connector is a safe no-op.

      Returns Promise<void>

      Resolves when the client has been destroyed.

    • Read a contiguous byte range from an S3 object using a GetObject request with a Range: bytes=offset-(offset+length-1) header.

      The S3 client is lazily initialized on the first call.

      Parameters

      • path: string

        S3 path in s3://bucket/key or bucket/key format.

      • offset: number

        Zero-based byte offset to begin reading from.

      • length: number

        Number of bytes to read.

      • Optionaloptions: ReadOptions

        Optional version check (IfMatch) and abort signal.

      Returns Promise<Uint8Array<ArrayBufferLike>>

      The requested byte range.

      If the request fails (with the HTTP status of the S3 error, e.g. 404 for NoSuchKey, 403 for AccessDenied), times out, or returns fewer bytes than its ContentRange announces.

      If the store ignores Range.

      If ifMatch no longer matches the object.

      If the @aws-sdk/client-s3 peer dependency is not installed (on first call only).

    • Read the first length bytes of an object together with its size (from ContentRange) and ETag.

      Parameters

      • path: string

        S3 path in s3://bucket/key or bucket/key format.

      • length: number

        Number of leading bytes to read.

      • Optionaloptions: ReadOptions

        Optional abort signal.

      Returns Promise<ReadHeadResult>

      The leading bytes plus size and version tag.

    • Read multiple byte ranges from the same S3 object.

      Each range is fetched as a separate GetObject call with a Range header, subject to the connector-wide S3ConnectorOptions.maxConcurrency limit. When one range fails, the others are cancelled. Results are returned in the same order as the input ranges.

      Parameters

      • path: string

        S3 path in s3://bucket/key or bucket/key format.

      • ranges: readonly { length: number; offset: number }[]

        Array of { offset, length } byte-range descriptors.

      • Optionaloptions: ReadOptions

        Optional version check and abort signal, applied to every range.

      Returns Promise<Uint8Array<ArrayBufferLike>[]>

      Array of Uint8Array chunks in the same order as the input ranges. Returns an empty array when ranges is empty.

      If any individual GetObject call fails after the request is issued.

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods