@graphty/graph-format 0.0.0 → 0.2.0

package/dist/src/columns/column.d.ts

@@ -0,0 +1,220 @@
+/**
+ * Column implementations for every dtype of design section 5.1, the column factory that wraps raw
+ * storage (MutableColumnParts) into a Column, the declaration resolver (ColumnDecl -> ColumnMeta,
+ * design sections 5.3 and 5.5), the constructors the table uses for typed arrays, JS arrays and
+ * empty declared columns. Bitmap and padding arithmetic comes from bitmap.ts and util/typed-array.ts.
+ *
+ * Storage follows Apache Arrow's layout without the dependency: a typed values buffer, an optional
+ * validity bitmap (u32 words, LSB-first, ceil(rows / 32) words -- the one bitmap layout of the
+ * package, decision C13), an optional dictionary, offsets or child, and per-column metadata. No
+ * per-row objects exist anywhere. Column contents are frozen by contract unless meta.mutable is true
+ * (design section 5.8); the mutable gating throws E_COLUMN_IMMUTABLE.
+ */
+import { type Column, type ColumnDeclPatch, type ColumnDomain, type ColumnMeta, type Dtype, type F32, type GpuEligibility, type I32, type TypedArrayData, type U8, type U32 } from "../types/index.js";
+import { type MutableColumnParts } from "../types/internal.js";
+import { DictionaryBuilder } from "./dictionary.js";
+type NumericDtype = "f32" | "f64" | "i32" | "u32" | "u8";
+/**
+ * Allocate a u8 store from which a zero-copy padded u32 view is constructible (design section 5.7):
+ * the backing buffer is a multiple of 4 bytes even when the length is not.
+ * @param length - the number of bytes
+ * @returns a fresh Uint8Array over a padded buffer
+ */
+export declare function allocU8(length: number): U8;
+/**
+ * GPU eligibility of a dtype (design section 10.4).
+ * @param dtype - the column dtype
+ * @returns "direct" for u32 / i32 / f32 / dict, "packed" for u8 / bool, "convert" for f64, "none" otherwise
+ */
+export declare function gpuEligibility(dtype: Dtype): GpuEligibility;
+/**
+ * Whether a value is a plain object (prototype Object.prototype or null), the only object shape JSON
+ * carries.
+ * @param value - the value to test
+ * @returns true for a plain object
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Reject a metadata value that JSON cannot carry (design section 5.9): only null, booleans, numbers
+ * (non-finite and -0 included; the wire tags them), well-formed strings, arrays and plain objects of
+ * such values are accepted. E_COLUMN_TYPE with details.field otherwise.
+ * @param value - the value to check
+ * @param field - the metadata field name for the error details
+ * @param depth - the nesting depth of `value` (E_COLUMN_TYPE beyond MAX_JSON_DEPTH)
+ */
+export declare function assertJsonValue(value: unknown, field: string, depth?: number): void;
+/**
+ * Whether a number is exactly representable in a numeric dtype: any number for f32 / f64, an integer
+ * in range for i32 / u32 / u8.
+ * @param dtype - the numeric dtype
+ * @param value - the number
+ * @returns true when the dtype stores the value without change
+ */
+export declare function representableNumber(dtype: NumericDtype, value: number): boolean;
+/**
+ * Resolve a column declaration into the complete metadata of design section 5.5: every field
+ * present, null for none, defaults applied, every rule checked (components, list child, refersTo,
+ * JSON-ness of default / options / extra, fill typing). E_COLUMN_TYPE with details.field on every
+ * violation.
+ * @param name - the column name (overrides decl.name)
+ * @param domain - the table the column belongs to
+ * @param decl - the declaration; dtype is required
+ * @returns the resolved metadata, frozen
+ */
+export declare function resolveColumnMeta(name: string, domain: ColumnDomain, decl: ColumnDeclPatch): ColumnMeta;
+/**
+ * The declaration that reproduces a column's metadata, for patching an existing column's meta
+ * (rename, move between tables, set() with a decl patch).
+ * @param meta - the metadata to convert
+ * @returns an equivalent declaration patch
+ */
+export declare function metaToDecl(meta: ColumnMeta): ColumnDeclPatch;
+/**
+ * Whether a value is an array-like of exactly `length` numbers (a multi-component cell).
+ * @param value - the value
+ * @param length - the required length
+ * @returns true for a numeric vector of that length
+ */
+export declare function isArrayLikeNumbers(value: unknown, length: number): value is ArrayLike<number>;
+/**
+ * Whether a value is a Column built by this package's factory (the structural Column type also
+ * admits a foreign object with the right members, which the table refuses with E_COLUMN_TYPE).
+ * @param value - the candidate
+ * @returns true for an instance of a column implementation
+ */
+export declare function isPackageColumn(value: unknown): value is Column;
+/**
+ * Whether a column's storage was transferred away (design section 9.1): derived from the array
+ * state. Every accessor of such a column throws E_DETACHED; the wire module and the checksum
+ * comparison ask first.
+ * @param column - any column
+ * @returns true when detached
+ */
+export declare function isColumnDetached(column: Column): boolean;
+/**
+ * Wrap raw column storage into a Column of the dtype named by parts.meta (the column factory of
+ * design section 5.7). Checks the slot use and the length rules of invariant I12 (E_COLUMN_LENGTH /
+ * E_COLUMN_TYPE / E_COLUMN_ALIGNMENT), recomputes nullCount from the validity bitmap, and adopts
+ * every buffer by reference.
+ * @param parts - the storage slots; every slot the dtype does not use must be null
+ * @returns the column
+ */
+export declare function createColumn(parts: MutableColumnParts): Column;
+/**
+ * The raw storage of a column, sharing every buffer by reference (the inverse of createColumn): used
+ * to re-wrap a column under new metadata and by the remap helpers.
+ * @param column - the column to unwrap
+ * @returns its storage slots
+ */
+export declare function partsOf(column: Column): MutableColumnParts;
+/**
+ * The distinct backing buffers of a column's materialised typed storage (data or codes, validity,
+ * a materialised Utf8 store, a list's offsets and child), for the owner count of design section
+ * 9.1: a table claims them when it attaches the column, so a buffer viewed from two tables (a
+ * zero-copy slice, a same-realm wire receiver) is recognised as shared. A string store that has not
+ * been materialised is not encoded by asking.
+ * @param column - the column
+ * @returns the buffers, each once
+ */
+export declare function columnBuffers(column: Column): ArrayBuffer[];
+/**
+ * The same storage under different metadata (a rename, a move to another table, a declaration
+ * patch); the buffers are shared, the Column object is new. The dtype, components and list child
+ * shape must be unchanged (E_COLUMN_TYPE otherwise); the fill is kept because the unset rows
+ * physically hold it; a nullable -> non-nullable change requires no unset rows.
+ * @param column - the column to re-wrap
+ * @param meta - the new metadata
+ * @returns a new column sharing the storage
+ */
+export declare function rewrapColumn(column: Column, meta: ColumnMeta): Column;
+/**
+ * Release the cached f32 copy a `gpuView()` of an f64 column keeps (design section 7.2:
+ * `dropCaches()` releases every cached gpuView copy). A no-op for every other dtype.
+ * @param column - the column
+ */
+export declare function dropGpuViewCache(column: Column): void;
+/**
+ * The array a GPU binds for a column (design section 10.4): its own data for u32 / i32 / f32, the
+ * padded view for u8, the packed words for bool, the codes for dict, and a cached f32 copy for f64
+ * (dropped by markDirty() and by GraphSnapshot.dropCaches()).
+ * @param column - the column
+ * @returns the bindable array; E_GPU_INELIGIBLE for string / list / json
+ */
+export declare function gpuViewOf(column: Column): U32 | I32 | F32;
+/**
+ * The initial dictionary of a dict column: the declared options in order, then the fill when it is
+ * a string not among them (so the fill code names a member).
+ * @param meta - the column metadata
+ * @returns the seeded dictionary builder
+ */
+export declare function seedDictionary(meta: ColumnMeta): DictionaryBuilder;
+/**
+ * A MutableColumnParts record with every storage slot null, for producers that fill one slot.
+ * @param meta - the column metadata
+ * @param length - the row count
+ * @param validity - the validity bitmap, or null
+ * @returns the parts
+ */
+export declare function emptyParts(meta: ColumnMeta, length: number, validity: U32 | null): MutableColumnParts;
+/**
+ * A column of `length` rows with no value set: every row unset (when nullable) and the data holding
+ * the fill (design section 5.3). This is what a declared column looks like before any value is
+ * written, and what remap uses for rows no source row maps to.
+ * @param domain - the table the column belongs to
+ * @param length - the number of rows
+ * @param decl - the declaration; dtype required
+ * @returns the empty column
+ */
+export declare function createEmptyColumn(domain: ColumnDomain, length: number, decl: ColumnDeclPatch): Column;
+/**
+ * A column from a JS array of values under resolved metadata (one entry per row; undefined, and null
+ * except for json, is an unset row). Values are coerced per design section 5.1 (a boolean into a
+ * number column becomes 1 / 0, a number or boolean into a string column its canonical text) and
+ * rejected with E_COLUMN_TYPE otherwise.
+ * @param meta - the resolved metadata
+ * @param values - the entries, `length` of them
+ * @returns the column
+ */
+export declare function columnOfValues(meta: ColumnMeta, values: readonly unknown[]): Column;
+/**
+ * Allocate a numeric buffer of a dtype (a padded store for u8).
+ * @param dtype - the numeric dtype
+ * @param length - the element count
+ * @returns the zeroed array
+ */
+export declare function allocNumeric(dtype: NumericDtype, length: number): TypedArrayData;
+/**
+ * A column from a JS array of values with a declaration patch (the set() path for string / list /
+ * json and for inferred dtypes). The dtype is inferred when the patch has none; nullable defaults to
+ * true.
+ * @param domain - the table the column belongs to
+ * @param length - the table's row count; E_COLUMN_LENGTH when values.length differs
+ * @param name - the column name
+ * @param values - the entries, one per row
+ * @param decl - the declaration patch
+ * @returns the column
+ */
+export declare function columnFromValues(domain: ColumnDomain, length: number, name: string, values: readonly unknown[], decl: ColumnDeclPatch): Column;
+/**
+ * The dtype a typed array class implies when the caller gave none.
+ * @param data - the array
+ * @returns f32 / f64 / i32 / u32 / u8
+ */
+export declare function dtypeOfArray(data: TypedArrayData): NumericDtype;
+/**
+ * A column adopting a typed array by reference (design section 5.7): the dtype comes from the array
+ * class unless the patch names one (bool and dict over a Uint32Array); the length must be rowCount *
+ * components (bool: ceil(rowCount / 32)) or E_COLUMN_LENGTH; a u8 array from which no padded u32 view
+ * is constructible is copied, or refused with E_COLUMN_ALIGNMENT under adopt "strict". nullable
+ * defaults to false (every row is set).
+ * @param domain - the table the column belongs to
+ * @param length - the table's row count
+ * @param name - the column name
+ * @param data - the typed array
+ * @param decl - the declaration patch
+ * @param adopt - "copy" (default) or "strict"
+ * @returns the column (`column.data !== data` only when a u8 array was copied)
+ */
+export declare function columnFromTypedArray(domain: ColumnDomain, length: number, name: string, data: TypedArrayData, decl: ColumnDeclPatch, adopt?: "copy" | "strict"): Column;
+export {};
+//# sourceMappingURL=column.d.ts.map

package/dist/src/columns/column.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column.d.ts","sourceRoot":"","sources":["../../../src/columns/column.ts"],"names":[],"mappings":"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"}