Neverending Puppy Marathon

    TypeScript icon, indicating that this package has built-in type declarations

    2.11.4 • Public • Published

    The Speckle Object Loader

    Twitter Follow Community forum users website docs npm version


    Comprehensive developer and user documentation can be found in our:

    📚 Speckle Docs website

    Getting started

    This is a small utility class that helps you stream an object and all its sub-components from the Speckle Server API. It is intended to be used in contexts where you want to "download" the whole object, or iteratively traverse its whole tree.


    If you've got this repo checked out locally, you can run yarn example to run an example web page running ObjectLoader in the browser at ''. This will run the example HTML found under ./examples/browser/'.

    To test ObjectLoader in a node environment, just run node ./examples/node/script.mjs

    In the browser

    Here's a sample way on how to use it, pilfered from the 3d viewer package:

    import ObjectLoader from '@speckle/objectloader';
    async load( { serverUrl, token, streamId, objectId } ) {
      const loader = new ObjectLoader( { serverUrl, token, streamId, objectId } )
      let total = null
      let count = 0
      for await ( let obj of loader.getObjectIterator() ) {
        if( !total ) total = obj.totalChildrenCount
        console.log( obj, `Progress: ${count++}/${total}` )

    If you do not want to process the objects one by one as they are streamed to you, you can use the getAndConstructObject() method. Here's an example:

    import ObjectLoader from '@speckle/objectloader'
    let loader = new ObjectLoader({
      serverUrl: '',
      streamId: '3ed8357f29',
      objectId: '0408ab9caaa2ebefb2dd7f1f671e7555',
      options: {
        fullyTraverseArrays: false, // Default: false. By default, if an array starts with a primitive type, it will not be traversed. Set it to true if you want to capture scenarios in which lists can have intersped objects and primitives, e.g. [ 1, 2, "a", { important object } ]
        excludeProps: ['displayValue', 'displayMesh', '__closure'] // Default: []. Any prop names that you pass in here will be ignored from object construction traversal.
    let obj = await loader.getAndConstructObject((e) => console.log('Progress', e))

    On the server

    Since Node.js does not yet support the fetch API, you'll need to provide your own fetch function in the options object, e.g., from node-fetch or cross-fetch

    import ObjectLoader from '@speckle/objectloader'
    import fetch from 'cross-fetch'
    let loader = new ObjectLoader({
      serverUrl: '',
      streamId: '3ed8357f29',
      objectId: '0408ab9caaa2ebefb2dd7f1f671e7555',
      options: { enableCaching: false, excludeProps: [], fetch }


    Run yarn build to build prod release, run yarn build:dev to build dev release. Or run yarn dev to run the build in watch mode.

    TS types

    The library isn't written in TypeScript so there's no typing information to be generated out of the box, but since we do want this library to be usable in TypeScript projects we write the types ourselves (for now).

    So whenever you make any changes to the API, make sure the types file in types/index.d.ts is updated


    If in trouble, the Speckle Community hangs out on the forum. Do join and introduce yourself! We're happy to help.


    Unless otherwise described, the code in this repository is licensed under the Apache-2.0 License. If you have any questions, don't hesitate to get in touch with us via email.


    npm i @speckle/objectloader

    DownloadsWeekly Downloads






    Unpacked Size

    62.4 kB

    Total Files


    Last publish


    • specklesystems
    • dimitrie