@botejs/core 0.6.0 → 0.8.0

package/README.md

@@ -7,22 +7,15 @@ npm install @botejs/core
 ```
 
 ```ts
-// node examples/citylots.js
-import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { open, fromFile } from '@botejs/core';
 
 // 181 MB GeoJSON:
 // { type: "...", features: [{ properties: { STREET: "..." }}] }
-const filePath = join(import.meta.dirname, 'citylots.json');
+const filePath = fileURLToPath(new URL('../citylots.json', import.meta.url));
 
 await using cursor = await open(fromFile(filePath));
 
-console.log(`type: ${await cursor.get('type')}`);
-// type: 'FeatureCollection'
-
-console.log(`features: ${await cursor.count('features')}`);
-// features: 206_560
-
 const byStreet = await cursor
   .iter('features', {
     select: ['properties', 'STREET'],
@@ -35,21 +28,34 @@ const byStreet = await cursor
   }, new Map());
 
 console.log([...byStreet].sort((a, b) => b[1] - a[1]).slice(0, 10));
-// [[ 'UNKNOWN', 2843 ], [ 'MASON', 2651 ], [ 'PINE', 1799 ], ... ]
 ```
 
-Given a **seekable** source (e.g. a file, an HTTP range) or "forward-only" source (e.g. HTTP GET request) and a path, it retrieves values out of a JSON, without loading the whole thing in-memory.
+Given a **seekable** or **forward** source and a path, it retrieves values out of a JSON, without loading the whole thing in-memory.
+
+Here's a run (Apple M1 Pro 2021, default settings, RUNS=100):
+
+| method             | mean time (seconds) | mean peak footprint (MB) |
+| ------------------ | -----------------   | ------------------------ |
+| bote               | 0.517 ± 0.018 s     | 40.3 ± 2.5               |
+| JSON.parse         | 0.816 ± 0.031 s     | 648.9 ± 2.4              |
+| JSONStream         | 4.452 ± 0.052 s     | 57.9 ± 3.9               |
+| @streamparser/json | 5.103 ± 0.084 s     | 47.9 ± 2.3               |
+| oboe.js            | 8.566 ± 0.295 s     | 100.0 ± 4.6              |
+| stream-json        | 13.346 ± 0.569 s    | 207.6 ± 8.4              |
+
+For comparison notes, go [here](https://github.com/jankdc/bote-comparison).
+
+## Features
+
+* Modern `AsyncIterator` API with helpers that emulate the [tc39 ones](https://github.com/tc39/proposal-async-iterator-helpers)
+* Validate with [Standard Schema](https://standardschema.dev/), avoiding those pesky `unknown`s
+* Supports multiple sources of data (e.g. file, network, stream) or write a custom one (see [example](./examples/))
+* For forward-only sources, there's support for replaying/buffering, allowing navigation to previous values
 
-Here's a comparison of running above (using Apple M1 Pro 2021's `/usr/bin/time -l`):
+## Documentation
 
-| method             | mean time | mean peak footprint (MB) |
-| ------------------ | --------- | ------------------------ |
-| JSON.parse         | 0.81 s    | 647.0                    |
-| bote               | 1.062 s   | 89.0                     |
-| @streamparser/json | 4.363 s   | 98.7                     |
-| JSONStream         | 4.417 s   | 60.7                     |
-| oboe.js            | 9.649 s   | 102.6                    |
-| stream-json        | 18.693 s  | 184.3                    |
+Coming soon. Check the [./examples](./examples/) folder for usages. I've also heavily JSDoc'ed the hell out of the API so have fun
+playing around with it for now.
 
 ## Status
 

package/dist/cursor.d.ts

@@ -43,13 +43,6 @@ export interface Cursor {
      */
     get(...path: Segment[]): Promise<unknown>;
     get<Sch extends StandardSchemaV1>(...args: [...Segment[], Sch]): Promise<InferOutput<Sch>>;
-    /**
-     * Count the members of the array or object at `path`.
-     *
-     * @example
-     * const total = await root.count('users');
-     */
-    count(...path: Segment[]): Promise<number>;
     /**
      * Stream the members of the array or object at `path` as an async iterable.
      * A trailing Standard Schema validates each item; a trailing {@link IterOptions}

package/dist/cursor.js

@@ -43,11 +43,6 @@ export function wrap(native, state) {
             }
             return runStandardSchema(schema, value, path);
         },
-        async count(...path) {
-            ensureOpen(state);
-            validatePath(path);
-            return withPath(path, () => native.count(path));
-        },
         iter(...args) {
             ensureOpen(state);
             const { path, tail } = splitArgs(args);

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export { type Source, type Reader, type ReadResult, type ForwardSource, type Fac
 export { fromFile, fromBuffer, fromHttpRange, type HttpRangeOptions } from './source/seekable.ts';
 export { fromReadable, fromHttpRequest, type ReadableOptions, type ReadableProducer, type HttpRequestOptions, } from './source/forward.ts';
 export { type IterStream } from './stream.ts';
-export { open, type OpenOptions, type ForwardOpenOptions } from './open.ts';
+export { open, type SeekableOpenOptions } from './open.ts';

package/dist/open.d.ts

@@ -1,7 +1,7 @@
 import { type RootCursor } from './cursor.ts';
 import type { SeekableSource, ForwardSource } from './source/base.ts';
 export declare const DEFAULT_SOURCE_CHUNK_BYTES: number;
-export interface OpenOptions {
+export interface SeekableOpenOptions {
     /**
      * How much of the index that speeds up repeat lookups to keep in memory,
      * measured in entries. Higher means faster repeat queries but more memory;
@@ -24,14 +24,6 @@ export interface OpenOptions {
      */
     arrayIndexInterval?: number;
 }
-/**
- * Options for a forward source: every cache knob is forbidden (the structural-index
- * cache is forced off). `Omit` would collapse to `{}` and silently permit them, so
- * the knobs are mapped to `never` to reject them at compile time.
- */
-export type ForwardOpenOptions = {
-    [K in keyof OpenOptions]?: never;
-};
 /**
  * Open a cursor over a source.
  *
@@ -43,5 +35,5 @@ export type ForwardOpenOptions = {
  * The returned `RootCursor` owns the reader: `close()` (or `await using`) drives
  * the reader's own `close()` exactly once.
  */
-export declare function open(source: SeekableSource, options?: OpenOptions): Promise<RootCursor>;
-export declare function open(source: ForwardSource, options?: ForwardOpenOptions): Promise<RootCursor>;
+export declare function open(source: SeekableSource, options?: SeekableOpenOptions): Promise<RootCursor>;
+export declare function open(source: ForwardSource): Promise<RootCursor>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botejs/core",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "prepublishOnly": "cp ../../README.md ./README.md && tsc"
   },
   "dependencies": {
-    "@botejs/native": "^0.6.0"
+    "@botejs/native": "^0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",