feat: Add Schema and Field withMetadata methods for metadata replacement

src/schema.ts

@@ -69,6 +69,16 @@ export class Schema<T extends TypeMap = any> {
         return new Schema<K>(fields, this.metadata);
     }
 
+    /**
+     * Create a new Schema with replaced metadata.
+     *
+     * @param metadata Replacement metadata entries. Pass `null` to clear.
+     */
+    public withMetadata(metadata: Map<string, string> | Record<string, string> | null): Schema<T> {
+        const next = metadata === null ? new Map<string, string>() : toMetadataMap(metadata);
+        return new Schema<T>(this.fields, next, undefined, this.metadataVersion);
+    }
+
     public assign<R extends TypeMap = any>(schema: Schema<R>): Schema<T & R>;
     public assign<R extends TypeMap = any>(...fields: (Field<R[keyof R]> | Field<R[keyof R]>[])[]): Schema<T & R>;
     public assign<R extends TypeMap = any>(...args: (Schema<R> | Field<R[keyof R]> | Field<R[keyof R]>[])[]) {
@@ -143,6 +153,17 @@ export class Field<T extends DataType = any> {
             : ({ name = this.name, type = this.type, nullable = this.nullable, metadata = this.metadata } = args[0]);
         return Field.new<R>(name, type, nullable, metadata);
     }
+
+    /**
+     * Create a new Field with replaced metadata. Accepts either a Map or a plain object.
+     * Pass `null` to clear existing metadata.
+     *
+     * @param metadata Replacement metadata entries.
+     */
+    public withMetadata(metadata: Map<string, string> | Record<string, string> | null): Field<T> {
+        const next = metadata === null ? new Map<string, string>() : toMetadataMap(metadata);
+        return new Field<T>(this.name, this.type, this.nullable, next);
+    }
 }
 
 // Add these here so they're picked up by the externs creator
@@ -157,6 +178,13 @@ function mergeMaps<TKey, TVal>(m1?: Map<TKey, TVal> | null, m2?: Map<TKey, TVal>
     return new Map([...(m1 || new Map()), ...(m2 || new Map())]);
 }
 
+/** @ignore */
+function toMetadataMap(metadata: Map<string, string> | Record<string, string>) {
+    return metadata instanceof Map
+        ? new Map(metadata)
+        : new Map(Object.entries(metadata));
+}
+
 /** @ignore */
 function generateDictionaryMap(fields: Field[], dictionaries = new Map<number, DataType>()): Map<number, DataType> {
 

test/unit/schema-tests.ts

@@ -0,0 +1,103 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+import '../jest-extensions.js';
+import { Field, Int32, Schema } from 'apache-arrow';
+
+describe('Field.withMetadata', () => {
+    test('replaces metadata from plain objects', () => {
+        const field = new Field('col', new Int32(), true, new Map([['foo', 'bar']]));
+        const input = { baz: 'qux' };
+        const updated = field.withMetadata(input);
+        expect(updated).not.toBe(field);
+        expect(updated.metadata.get('foo')).toBeUndefined();
+        expect(updated.metadata.get('baz')).toBe('qux');
+        expect(field.metadata.get('foo')).toBe('bar');
+        expect(field.metadata.get('baz')).toBeUndefined();
+        // Mutating the input after the call should not affect the result
+        input.baz = 'changed';
+        (input as any).newKey = 'newValue';
+        expect(updated.metadata.get('baz')).toBe('qux');
+        expect(updated.metadata.get('newKey')).toBeUndefined();
+    });
+
+    test('replaces metadata from Maps', () => {
+        const field = new Field('col', new Int32(), true, new Map([['foo', 'bar']]));
+        const input = new Map([['foo', 'baz']]);
+        const updated = field.withMetadata(input);
+        expect(updated.metadata.get('foo')).toBe('baz');
+        expect(updated.metadata.size).toBe(1);
+        expect(field.metadata.get('foo')).toBe('bar');
+        expect(field.metadata.size).toBe(1);
+        // Mutating the input after the call should not affect the result
+        input.set('foo', 'qux');
+        input.set('newKey', 'newValue');
+        expect(updated.metadata.get('foo')).toBe('baz');
+        expect(updated.metadata.get('newKey')).toBeUndefined();
+        expect(updated.metadata.size).toBe(1);
+    });
+
+    test('clears metadata when null is passed', () => {
+        const field = new Field('col', new Int32(), true, new Map([['foo', 'bar']]));
+        const updated = field.withMetadata(null);
+        expect(updated.metadata.size).toBe(0);
+        expect(field.metadata.get('foo')).toBe('bar');
+        expect(field.metadata.size).toBe(1);
+    });
+});
+
+describe('Schema.withMetadata', () => {
+    test('replaces metadata from plain objects', () => {
+        const schema = new Schema([new Field('col', new Int32())], new Map([['foo', 'bar']]));
+        const input = { baz: 'qux' };
+        const updated = schema.withMetadata(input);
+        expect(updated).not.toBe(schema);
+        expect(schema.metadata.get('baz')).toBeUndefined();
+        expect(schema.metadata.get('foo')).toBe('bar');
+        expect(updated.metadata.get('foo')).toBeUndefined();
+        expect(updated.metadata.get('baz')).toBe('qux');
+        // Mutating the input after the call should not affect the result
+        input.baz = 'changed';
+        (input as any).newKey = 'newValue';
+        expect(updated.metadata.get('baz')).toBe('qux');
+        expect(updated.metadata.get('newKey')).toBeUndefined();
+    });
+
+    test('replaces metadata from Maps', () => {
+        const schema = new Schema([new Field('col', new Int32())], new Map([['foo', 'bar']]));
+        const input = new Map([['foo', 'baz']]);
+        const updated = schema.withMetadata(input);
+        expect(updated.metadata.get('foo')).toBe('baz');
+        expect(updated.metadata.size).toBe(1);
+        expect(schema.metadata.get('foo')).toBe('bar');
+        expect(schema.metadata.size).toBe(1);
+        // Mutating the input after the call should not affect the result
+        input.set('foo', 'qux');
+        input.set('newKey', 'newValue');
+        expect(updated.metadata.get('foo')).toBe('baz');
+        expect(updated.metadata.get('newKey')).toBeUndefined();
+        expect(updated.metadata.size).toBe(1);
+    });
+
+    test('clears metadata when null is passed', () => {
+        const schema = new Schema([new Field('col', new Int32())], new Map([['foo', 'bar']]));
+        const updated = schema.withMetadata(null);
+        expect(updated.metadata.size).toBe(0);
+        expect(schema.metadata.get('foo')).toBe('bar');
+        expect(schema.metadata.size).toBe(1);
+    });
+});