Specifically, change 'getItem()' to just 'at()' and support negative index semantics:
https://github.com/tc39/proposal-relative-indexing-method

Excitingly, this means that Array, TypedArray, and String will just "happen to be" IVectorReaders, etc. the same way Map "happens to be" an IMapReader, etc.

EDIT: Proposal is now to add 'at()' rather than 'item()'

Allow the parser to take a custom error handler that does not allocate for each error - instead writing to a one-shot Boolean.

/cc @DLehenbauer Input welcome but a low priority issue for the moment.

Some potential differences between maps/records that may motivate a separate contract:

• The set of keys in a map is dynamic (i.e., no fixed schema)
• It is not an error to read non-existent keys (returns undefined)
• You can test for the presence of a key, get a count of entries, and enumerate map entries, key, values.
• You can delete keys and clear a map.

I think we could probably expose these as an extension of the record interfaces:

interface IMapReader<TKey, TValue> extends IReader<Record<TKey, TValue | undefined>> {
    has(key: TKey): boolean;
    entries(): IEnumarable<[TKey, TValue]>;
    keys(): IEnumarable<TKey>;
    values(): IEnumarable<TValue>;
    readonly size: number;
}

interface IMapWriter<TKey, TValue> extends IWriter<Record<TKey, TValue>> {
    delete(key: TKey): void;
    clear(): void;
}

• Add cell refs to the parser and ast structure.
• Switch formula evaluator to interpreter.
• Implement row/col insertion and deletion.

Items for the next iteration of nano.

• Quoted field names like A.{Foo Bar Baz} #42
• Tree-based interpreter. #44
• Tracing and effects refactor. #43
• Better error handling. #44
• Build out more examples. #45
• First cut and explicit API for core properties like value and stringify. #43 (more work to be done).

Currently a missing node will cause the compiler to throw an exception.

Alternatives include:

• interpret missing as a value
• catch the error and return undefined
• call back into the parser error handler if such an API was exposed; related: #15.

Rename to mirror new producer types.

scanNumber needs to look if the charactor following a dot is the start of a string literal (we already check for identifiers).

One seemingly simple thing that I think would benefit the JavaScript ecosystem in general are a set of standard contracts for observable data types that allow reactive systems to interoperate (e.g., a standard mechanism for an ObservableMap implementer to notify observers when keys are added, removed, or changed.)

@jack-williams and I have been slowly refining a set of such interfaces for Tiny-Calc, and I've made a first attempt at describing our thinking here.

I'd be interested in @taylorsw04, @CraigMacomber's thoughts/suggestions on the design (or improving the README. I feel like it sounds more complex than it is when I try to describe it.)

Array.splice() accepts a set of items to insert, where IVectorShapeWriter takes a number of default items / holes to insert.

Array.splice(start: number, deleteCount: number, ...items: T[]): T[];
IVectorShapeWriter.splice(start: number, deleteCount: number, insertCount: number): void;

The motivations for this inconsistency were:

1. The spread operator ('...items[]') can lead to stack exhaustion when the number of items inserted is large on v8 (v12 x64).
2. Providing the items up front encourages potentially unnecessary array allocations/copies.
3. Philosophically, IVectorShapeWriter should be agnostic to the type of items stored (i.e., should not have a generic T param)

(Issues 1 & 2 have proven to be real concerns for IMatrix, which has similar spliceRows/Cols APIs)

However, in practice this API difference has proven to be error-prone for IVector. This is because when T=number, both signatures will accept '.splice(0, 0, 3)', which Array would interpret as insert '3' and IVector interprets as insert 3 holes.

(It's also just clunky/annoying to have to call splice() and then use setItem() to fill in the holes.)

My current thinking is that we should rename IShapeWriter.splice to avoid confusion (and perhaps reintroduce a compatible splice on I*Writer.)

...if only I could think of a good name... The best I have so far is 'resize()', but that might be a discovery issue as 'resize()' is usually used for modifying length only.

PS - There is a second inconsistency where IVectorShapeWriter.splice() returns void instead of an array of the removed items, but I believe here there is far more upside.

Researching various API nits to see if I can find a compelling majority. (Feel free to comment/add).

Conventions

Intervals expressed as start/count?

Currently I use start/count because it's unambiguous wrt. if the 'end' is inclusive/exclusive.

insertRows(startRow: number, numRows: number);

• Excel does the same.
• Math.js uses inclusive start / exclusive end.
• Most modern JavaScript APIs use start / end (exclusive).

Points, intervals, etc. are open-coded as numbers (as opposed to arrays, objects, etc.)

This was done out of fear of hidden array/object allocations, but never verified.

read(rowStart: number, colStart: number, rowCount: number, colCount: number);

Vector, Matrix, etc. are distinct types.

Related to the above, if we were to pass coordinates/sizes as arrays, we could generalize vectors, matrices, etc. to n-dimensional arrays.

Naming

'col' as an abbreviation for column?

insertCol(col: number, numCols: number);

• Excel does not abbreviate.
• Math.js does not abbreviate.

'numRows' as an abbreviation for 'number of rows'?

• Excel uses 'rowCount', which is probably easier to discover in Intellisense.
• Math.js has a single '.size' property that returns a [number, number].
• ndarray has a single '.shape' property that returns a 'number[]'.

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request