ARROW-10255: [JS] Reorganize exports for ESM tree-shaking

js/DEVELOP.md

@@ -18,6 +18,7 @@
 -->
 
 # Getting Involved
+
 Even if you do not plan to contribute to Apache Arrow itself or Arrow
 integrations in other projects, we'd be happy to have you involved:
 
@@ -68,29 +69,41 @@ Uses [lerna](https://github.com/lerna/lerna) to publish each build target to npm
 
 1. Once generated, the flatbuffers format code needs to be adjusted for our build scripts (assumes `gnu-sed`):
 
-```shell
-cd $ARROW_HOME
-
-flatc --ts -o ./js/src/fb ./format/{File,Schema,Message}.fbs
-
-cd ./js/src/fb
-
-# Rename the existing files to <filename>.bak.ts
-mv File{,.bak}.ts && mv Schema{,.bak}.ts && mv Message{,.bak}.ts
-
-# Remove `_generated` from the ES6 imports of the generated files
-sed -i '+s+_generated\";+\";+ig' *_generated.ts
-# Fix all the `flatbuffers` imports
-sed -i '+s+./flatbuffers+flatbuffers+ig' *_generated.ts
-# Fix the Union createTypeIdsVector typings
-sed -i -r '+s+static createTypeIdsVector\(builder: flatbuffers.Builder, data: number\[\] \| Uint8Array+static createTypeIdsVector\(builder: flatbuffers.Builder, data: number\[\] \| Int32Array+ig' Schema_generated.ts
-# Add `/* tslint:disable:class-name */` to the top of `Schema.ts`
-echo -e '/* tslint:disable:class-name */\n' | cat - Schema_generated.ts > Schema1.ts && mv Schema1.ts Schema_generated.ts
-# Remove "_generated" suffix from TS files
-mv File{_generated,}.ts && mv Schema{_generated,}.ts && mv Message{_generated,}.ts
-```
-2. Manually remove `Tensor` and `SparseTensor` imports and exports
-3. Execute `npm run lint` from the `js` directory to fix the linting errors
+    ```shell
+    cd $ARROW_HOME
+
+    # Create a tmpdir to store modified flatbuffers schemas
+    tmp_format_dir=$(mktemp -d)
+    cp ./format/*.fbs $tmp_format_dir
+
+    # Remove namespaces from the flatbuffers schemas
+    sed -i '+s+namespace org.apache.arrow.flatbuf;++ig' $tmp_format_dir/*.fbs
+    sed -i '+s+org.apache.arrow.flatbuf.++ig' $tmp_format_dir/*.fbs
+
+    # Generate TS source from the modified Arrow flatbuffers schemas
+    flatc --ts --no-ts-reexport -o ./js/src/fb $tmp_format_dir/{File,Schema,Message}.fbs
+
+    # Remove the tmpdir
+    rm -rf $tmp_format_dir
+
+    cd ./js/src/fb
+
+    # Rename the existing files to <filename>.bak.ts
+    mv File{,.bak}.ts && mv Schema{,.bak}.ts && mv Message{,.bak}.ts
+
+    # Remove `_generated` from the ES6 imports of the generated files
+    sed -i '+s+_generated\";+\";+ig' *_generated.ts
+    # Fix all the `flatbuffers` imports
+    sed -i '+s+./flatbuffers+flatbuffers+ig' *_generated.ts
+    # Fix the Union createTypeIdsVector typings
+    sed -i -r '+s+static createTypeIdsVector\(builder: flatbuffers.Builder, data: number\[\] \| Uint8Array+static createTypeIdsVector\(builder: flatbuffers.Builder, data: number\[\] \| Int32Array+ig' Schema_generated.ts
+    # Add `/* tslint:disable:class-name */` to the top of `Schema.ts`
+    echo -e '/* tslint:disable:class-name */\n' | cat - Schema_generated.ts > Schema1.ts && mv Schema1.ts Schema_generated.ts
+    # Remove "_generated" suffix from TS files
+    mv File{_generated,}.ts && mv Schema{_generated,}.ts && mv Message{_generated,}.ts
+    ```
+
+2. Execute `npm run lint` from the `js` directory to fix the linting errors
 
 [1]: mailto:dev-subscribe@arrow.apache.org
 [2]: https://github.com/apache/arrow/tree/master/format

js/gulp/package-task.js

@@ -52,7 +52,8 @@ const createMainPackageJson = (target, format) => (orig) => ({
     types: `${mainExport}.node.d.ts`,
     unpkg: `${mainExport}.es5.min.js`,
     jsdelivr: `${mainExport}.es5.min.js`,
-    esm: { mode: `all`, sourceMap: true }
+    sideEffects: false,
+    esm: { mode: `all`, sourceMap: true },
 });
 
 const createTypeScriptPackageJson = (target, format) => (orig) => ({
@@ -86,6 +87,8 @@ const createScopedPackageJSON = (target, format) => (({ name, ...orig }) =>
             main:     format === 'umd' ? `${mainExport}.js` : `${mainExport}.node`,
             // set "module" (for https://www.npmjs.com/package/@pika/pack) if building scoped ESM target
             module:   format === 'esm' ? `${mainExport}.dom.js` : undefined,
+            // set "sideEffects" to false as a hint to Webpack that it's safe to tree-shake the ESM target
+            sideEffects: format === 'esm' ? false : undefined,
             // include "esm" settings for https://www.npmjs.com/package/esm if building scoped ESM target
             esm:      format === `esm` ? { mode: `auto`, sourceMap: true } : undefined,
             // set "types" (for TypeScript/VSCode)

js/package.json

@@ -62,7 +62,7 @@
     "@types/text-encoding-utf-8": "^1.0.1",
     "command-line-args": "5.0.2",
     "command-line-usage": "5.0.5",
-    "flatbuffers": "1.11.0",
+    "flatbuffers": "1.12.0",
     "json-bignum": "^0.0.3",
     "pad-left": "^2.1.0",
     "text-encoding-utf-8": "^1.0.2",

js/src/Arrow.dom.ts

@@ -17,8 +17,8 @@
 
 import streamAdapters from './io/adapters';
 import { Builder } from './builder/index';
-import { RecordBatchReader } from './ipc/reader';
-import { RecordBatchWriter } from './ipc/writer';
+import { RecordBatchReader, RecordBatchFileReader, RecordBatchStreamReader, } from './ipc/reader';
+import { RecordBatchWriter, RecordBatchFileWriter, RecordBatchStreamWriter, } from './ipc/writer';
 import { toDOMStream } from './io/whatwg/iterable';
 import { builderThroughDOMStream } from './io/whatwg/builder';
 import { recordBatchReaderThroughDOMStream } from './io/whatwg/reader';
@@ -27,10 +27,14 @@ import { recordBatchWriterThroughDOMStream } from './io/whatwg/writer';
 streamAdapters.toDOMStream = toDOMStream;
 Builder['throughDOM'] = builderThroughDOMStream;
 RecordBatchReader['throughDOM'] = recordBatchReaderThroughDOMStream;
+RecordBatchFileReader['throughDOM'] = recordBatchReaderThroughDOMStream;
+RecordBatchStreamReader['throughDOM'] = recordBatchReaderThroughDOMStream;
 RecordBatchWriter['throughDOM'] = recordBatchWriterThroughDOMStream;
+RecordBatchFileWriter['throughDOM'] = recordBatchWriterThroughDOMStream;
+RecordBatchStreamWriter['throughDOM'] = recordBatchWriterThroughDOMStream;
 
 export {
-    ArrowType, DateUnit, IntervalUnit, MessageHeader, MetadataVersion, Precision, TimeUnit, Type, UnionMode, BufferType,
+    DateUnit, IntervalUnit, MessageHeader, MetadataVersion, Precision, TimeUnit, Type, UnionMode, BufferType,
     Data,
     DataType,
     Null,

js/src/Arrow.ts

@@ -15,7 +15,19 @@
 // specific language governing permissions and limitations
 // under the License.
 
-export { ArrowType, DateUnit, IntervalUnit, MessageHeader, MetadataVersion, Precision, TimeUnit, Type, UnionMode, BufferType } from './enum';
+export {
+    DateUnit,
+    TimeUnit,
+    Precision,
+    UnionMode,
+    IntervalUnit,
+    MetadataVersion,
+} from './fb/Schema';
+
+export { MessageHeader } from './fb/Message';
+
+export { Type, BufferType } from './enum';
+
 export { Data } from './data';
 export {
     DataType,
@@ -105,6 +117,7 @@ import * as util_math_ from './util/math';
 import * as util_buffer_ from './util/buffer';
 import * as util_vector_ from './util/vector';
 import * as predicate from './compute/predicate';
+import { compareSchemas, compareFields, compareTypes } from './visitor/typecomparator';
 
 export { predicate };
 /** @ignore */
@@ -114,5 +127,8 @@ export const util = {
     ...util_bit_,
     ...util_math_,
     ...util_buffer_,
-    ...util_vector_
+    ...util_vector_,
+    compareSchemas,
+    compareFields,
+    compareTypes,
 };

js/src/enum.ts

@@ -15,17 +15,16 @@
 // specific language governing permissions and limitations
 // under the License.
 
-import * as Schema_ from './fb/Schema';
-import * as Message_ from './fb/Message';
+export {
+    DateUnit,
+    TimeUnit,
+    Precision,
+    UnionMode,
+    IntervalUnit,
+    MetadataVersion,
+} from './fb/Schema';
 
-export import ArrowType = Schema_.org.apache.arrow.flatbuf.Type;
-export import DateUnit = Schema_.org.apache.arrow.flatbuf.DateUnit;
-export import TimeUnit = Schema_.org.apache.arrow.flatbuf.TimeUnit;
-export import Precision = Schema_.org.apache.arrow.flatbuf.Precision;
-export import UnionMode = Schema_.org.apache.arrow.flatbuf.UnionMode;
-export import IntervalUnit = Schema_.org.apache.arrow.flatbuf.IntervalUnit;
-export import MessageHeader = Message_.org.apache.arrow.flatbuf.MessageHeader;
-export import MetadataVersion = Schema_.org.apache.arrow.flatbuf.MetadataVersion;
+export { MessageHeader } from './fb/Message';
 
 /**
  * Main data type enumeration.