2023-04-25 11:01:25 +00:00
|
|
|
## API Report File for "@tldraw/utils"
|
|
|
|
|
|
|
|
> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
|
|
|
|
|
|
|
|
```ts
|
|
|
|
|
|
|
|
// @internal
|
|
|
|
export function annotateError(error: unknown, annotations: Partial<ErrorAnnotations>): void;
|
|
|
|
|
2023-12-01 16:48:30 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export function areArraysShallowEqual<T>(arr1: readonly T[], arr2: readonly T[]): boolean;
|
|
|
|
|
|
|
|
// @internal (undocumented)
|
|
|
|
export function areObjectsShallowEqual<T extends Record<string, unknown>>(obj1: T, obj2: T): boolean;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export const assert: (value: unknown, message?: string) => asserts value;
|
|
|
|
|
|
|
|
// @internal (undocumented)
|
|
|
|
export const assertExists: <T>(value: T, message?: string | undefined) => NonNullable<T>;
|
|
|
|
|
2024-03-04 16:15:20 +00:00
|
|
|
// @internal
|
|
|
|
export function clearLocalStorage(): void;
|
|
|
|
|
|
|
|
// @internal
|
|
|
|
export function clearSessionStorage(): void;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export function compact<T>(arr: T[]): NonNullable<T>[];
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function debounce<T extends unknown[], U>(callback: (...args: T) => PromiseLike<U> | U, wait: number): {
|
|
|
|
(...args: T): Promise<U>;
|
|
|
|
cancel(): void;
|
|
|
|
};
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function dedupe<T>(input: T[], equals?: (a: any, b: any) => boolean): T[];
|
|
|
|
|
2024-03-04 16:15:20 +00:00
|
|
|
// @internal
|
|
|
|
export function deleteFromLocalStorage(key: string): void;
|
|
|
|
|
|
|
|
// @internal
|
|
|
|
export function deleteFromSessionStorage(key: string): void;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @public (undocumented)
|
|
|
|
export type ErrorResult<E> = {
|
|
|
|
readonly ok: false;
|
|
|
|
readonly error: E;
|
|
|
|
};
|
|
|
|
|
|
|
|
// @internal (undocumented)
|
|
|
|
export function exhaustiveSwitchError(value: never, property?: string): never;
|
|
|
|
|
2023-06-16 10:33:47 +00:00
|
|
|
// @public (undocumented)
|
|
|
|
export type Expand<T> = T extends infer O ? {
|
|
|
|
[K in keyof O]: O[K];
|
|
|
|
} : never;
|
|
|
|
|
2023-07-19 10:50:40 +00:00
|
|
|
// @public
|
|
|
|
export class FileHelpers {
|
2024-03-12 16:51:29 +00:00
|
|
|
static blobToDataUrl(file: Blob): Promise<string>;
|
|
|
|
static blobToText(file: Blob): Promise<string>;
|
|
|
|
// (undocumented)
|
|
|
|
static dataUrlToArrayBuffer(dataURL: string): Promise<ArrayBuffer>;
|
2023-07-19 10:50:40 +00:00
|
|
|
}
|
|
|
|
|
derived presence state (#1204)
This PR adds
- A new `TLInstancePresence` record type, to collect info about the
presence state in a particular instance of the editor. This will
eventually be used to sync presence data instead of sending
instance-only state across the wire.
- **Record Scopes**
`RecordType` now has a `scope` property which can be one of three
things:
- `document`: the record belongs to the document and should be synced
and persisted freely. Currently: `TLDocument`, `TLPage`, `TLShape`, and
`TLAsset`
- `instance`: the record belongs to a single instance of the store and
should not be synced at all. It should not be persisted directly in most
cases, but rather compiled into a kind of 'instance configuration' to
store alongside the local document data so that when reopening the
associated document it can remember some of the previous instance state.
Currently: `TLInstance`, `TLInstancePageState`, `TLCamera`, `TLUser`,
`TLUserDocument`, `TLUserPresence`
- `presence`: the record belongs to a single instance of the store and
should not be persisted, but may be synced using the special presence
sync protocol. Currently just `TLInstancePresence`
This sets us up for the following changes, which are gonna be pretty
high-impact in terms of integrating tldraw into existing systems:
- Removing `instanceId` as a config option. Each instance gets a
randomly generated ID.
- We'd replace it with an `instanceConfig` option that has stuff like
selectedIds, camera positions, and so on. Then it's up to library users
to get and reinstate the instance config at persistence boundaries.
- Removing `userId` as config option, and removing the `TLUser` type
altogether.
- We might need to revisit when doing auth-enabled features like locking
shapes, but I suspect that will be separate.
2023-04-27 18:03:19 +00:00
|
|
|
// @internal
|
|
|
|
export function filterEntries<Key extends string, Value>(object: {
|
|
|
|
[K in Key]: Value;
|
|
|
|
}, predicate: (key: Key, value: Value) => boolean): {
|
|
|
|
[K in Key]: Value;
|
|
|
|
};
|
|
|
|
|
2024-03-11 13:17:31 +00:00
|
|
|
// @internal
|
|
|
|
export function fpsThrottle(fn: () => void): () => void;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export function getErrorAnnotations(error: Error): ErrorAnnotations;
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function getFirstFromIterable<T = unknown>(set: Map<any, T> | Set<T>): T;
|
|
|
|
|
2024-03-04 16:15:20 +00:00
|
|
|
// @internal
|
|
|
|
export function getFromLocalStorage(key: string): null | string;
|
|
|
|
|
|
|
|
// @internal
|
|
|
|
export function getFromSessionStorage(key: string): null | string;
|
|
|
|
|
2024-01-10 14:41:18 +00:00
|
|
|
// @public
|
|
|
|
export function getHashForBuffer(buffer: ArrayBuffer): string;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @public
|
|
|
|
export function getHashForObject(obj: any): string;
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function getHashForString(string: string): string;
|
|
|
|
|
2024-02-14 17:53:30 +00:00
|
|
|
// @public
|
|
|
|
export function getIndexAbove(below: IndexKey): IndexKey;
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function getIndexBelow(above: IndexKey): IndexKey;
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function getIndexBetween(below: IndexKey, above?: IndexKey): IndexKey;
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function getIndices(n: number, start?: IndexKey): IndexKey[];
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function getIndicesAbove(below: IndexKey, n: number): IndexKey[];
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function getIndicesBelow(above: IndexKey, n: number): IndexKey[];
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function getIndicesBetween(below: IndexKey | undefined, above: IndexKey | undefined, n: number): IndexKey[];
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export function getOwnProperty<K extends string, V>(obj: Partial<Record<K, V>>, key: K): undefined | V;
|
|
|
|
|
|
|
|
// @internal (undocumented)
|
|
|
|
export function getOwnProperty(obj: object, key: string): unknown;
|
|
|
|
|
|
|
|
// @internal (undocumented)
|
|
|
|
export function hasOwnProperty(obj: object, key: string): boolean;
|
|
|
|
|
2024-02-14 17:53:30 +00:00
|
|
|
// @public
|
|
|
|
export type IndexKey = string & {
|
|
|
|
__orderKey: true;
|
|
|
|
};
|
|
|
|
|
2024-02-07 10:40:01 +00:00
|
|
|
// @public
|
|
|
|
export function invLerp(a: number, b: number, t: number): number;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @public
|
|
|
|
export function isDefined<T>(value: T): value is typeof value extends undefined ? never : T;
|
|
|
|
|
use native structuredClone on node, cloudflare workers, and in tests (#3166)
Currently, we only use native `structuredClone` in the browser, falling
back to `JSON.parse(JSON.stringify(...))` elsewhere, despite Node
supporting `structuredClone` [since
v17](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone)
and Cloudflare Workers supporting it [since
2022](https://blog.cloudflare.com/standards-compliant-workers-api/).
This PR adjusts our shim to use the native `structuredClone` on all
platforms, if available.
Additionally, `jsdom` doesn't implement `structuredClone`, a bug [open
since 2022](https://github.com/jsdom/jsdom/issues/3363). This PR patches
`jsdom` environment in all packages/apps that use it for tests.
Also includes a driveby removal of `deepCopy`, a function that is
strictly inferior to `structuredClone`.
### Change Type
<!-- ❗ Please select a 'Scope' label ❗️ -->
- [x] `sdk` — Changes the tldraw SDK
- [x] `dotcom` — Changes the tldraw.com web app
- [ ] `docs` — Changes to the documentation, examples, or templates.
- [ ] `vs code` — Changes to the vscode plugin
- [ ] `internal` — Does not affect user-facing stuff
<!-- ❗ Please select a 'Type' label ❗️ -->
- [ ] `bugfix` — Bug fix
- [ ] `feature` — New feature
- [x] `improvement` — Improving existing features
- [x] `chore` — Updating dependencies, other boring stuff
- [ ] `galaxy brain` — Architectural changes
- [ ] `tests` — Changes to any test code
- [ ] `tools` — Changes to infrastructure, CI, internal scripts,
debugging tools, etc.
- [ ] `dunno` — I don't know
### Test Plan
1. A smoke test would be enough
- [ ] Unit Tests
- [x] End to end tests
2024-03-18 17:16:09 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export const isNativeStructuredClone: boolean;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @public
|
|
|
|
export function isNonNull<T>(value: T): value is typeof value extends null ? never : T;
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function isNonNullish<T>(value: T): value is typeof value extends undefined ? never : typeof value extends null ? never : T;
|
|
|
|
|
2023-06-28 14:24:05 +00:00
|
|
|
// @public (undocumented)
|
|
|
|
export type JsonArray = JsonValue[];
|
|
|
|
|
|
|
|
// @public (undocumented)
|
|
|
|
export type JsonObject = {
|
|
|
|
[key: string]: JsonValue | undefined;
|
|
|
|
};
|
|
|
|
|
|
|
|
// @public (undocumented)
|
|
|
|
export type JsonPrimitive = boolean | null | number | string;
|
|
|
|
|
|
|
|
// @public (undocumented)
|
|
|
|
export type JsonValue = JsonArray | JsonObject | JsonPrimitive;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export function last<T>(arr: readonly T[]): T | undefined;
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function lerp(a: number, b: number, t: number): number;
|
|
|
|
|
|
|
|
// @public (undocumented)
|
|
|
|
export function lns(str: string): string;
|
|
|
|
|
2023-06-12 14:04:14 +00:00
|
|
|
// @internal
|
|
|
|
export function mapObjectMapValues<Key extends string, ValueBefore, ValueAfter>(object: {
|
|
|
|
readonly [K in Key]: ValueBefore;
|
|
|
|
}, mapper: (key: Key, value: ValueBefore) => ValueAfter): {
|
|
|
|
[K in Key]: ValueAfter;
|
|
|
|
};
|
|
|
|
|
2023-07-19 10:50:40 +00:00
|
|
|
// @public
|
|
|
|
export class MediaHelpers {
|
2024-01-10 14:41:18 +00:00
|
|
|
static getImageSize(blob: Blob): Promise<{
|
2023-07-19 10:50:40 +00:00
|
|
|
w: number;
|
|
|
|
h: number;
|
|
|
|
}>;
|
2024-01-10 14:41:18 +00:00
|
|
|
static getVideoSize(blob: Blob): Promise<{
|
2023-07-19 10:50:40 +00:00
|
|
|
w: number;
|
|
|
|
h: number;
|
|
|
|
}>;
|
2024-01-10 14:41:18 +00:00
|
|
|
static loadImage(src: string): Promise<HTMLImageElement>;
|
|
|
|
static loadVideo(src: string): Promise<HTMLVideoElement>;
|
|
|
|
// (undocumented)
|
|
|
|
static usingObjectURL<T>(blob: Blob, fn: (url: string) => Promise<T>): Promise<T>;
|
2023-07-19 10:50:40 +00:00
|
|
|
}
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export function minBy<T>(arr: readonly T[], fn: (item: T) => number): T | undefined;
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function modulate(value: number, rangeA: number[], rangeB: number[], clamp?: boolean): number;
|
|
|
|
|
2023-06-12 14:04:14 +00:00
|
|
|
// @internal
|
|
|
|
export function noop(): void;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @internal
|
|
|
|
export function objectMapEntries<Key extends string, Value>(object: {
|
|
|
|
[K in Key]: Value;
|
|
|
|
}): Array<[Key, Value]>;
|
|
|
|
|
2023-05-24 11:25:41 +00:00
|
|
|
// @internal
|
|
|
|
export function objectMapFromEntries<Key extends string, Value>(entries: ReadonlyArray<readonly [Key, Value]>): {
|
|
|
|
[K in Key]: Value;
|
|
|
|
};
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @internal
|
|
|
|
export function objectMapKeys<Key extends string>(object: {
|
|
|
|
readonly [K in Key]: unknown;
|
|
|
|
}): Array<Key>;
|
|
|
|
|
|
|
|
// @internal
|
|
|
|
export function objectMapValues<Key extends string, Value>(object: {
|
|
|
|
[K in Key]: Value;
|
|
|
|
}): Array<Value>;
|
|
|
|
|
|
|
|
// @public (undocumented)
|
|
|
|
export type OkResult<T> = {
|
|
|
|
readonly ok: true;
|
|
|
|
readonly value: T;
|
|
|
|
};
|
|
|
|
|
|
|
|
// @internal
|
|
|
|
export function omitFromStackTrace<Args extends Array<unknown>, Return>(fn: (...args: Args) => Return): (...args: Args) => Return;
|
|
|
|
|
|
|
|
// @internal
|
|
|
|
export function partition<T>(arr: T[], predicate: (item: T) => boolean): [T[], T[]];
|
|
|
|
|
2023-07-19 10:50:40 +00:00
|
|
|
// @public (undocumented)
|
|
|
|
export class PngHelpers {
|
|
|
|
// (undocumented)
|
|
|
|
static findChunk(view: DataView, type: string): {
|
|
|
|
dataOffset: number;
|
|
|
|
size: number;
|
|
|
|
start: number;
|
|
|
|
};
|
|
|
|
// (undocumented)
|
|
|
|
static getChunkType(view: DataView, offset: number): string;
|
|
|
|
// (undocumented)
|
|
|
|
static isPng(view: DataView, offset: number): boolean;
|
|
|
|
// (undocumented)
|
|
|
|
static parsePhys(view: DataView, offset: number): {
|
|
|
|
ppux: number;
|
|
|
|
ppuy: number;
|
|
|
|
unit: number;
|
|
|
|
};
|
|
|
|
// (undocumented)
|
|
|
|
static readChunks(view: DataView, offset?: number): Record<string, {
|
|
|
|
dataOffset: number;
|
|
|
|
size: number;
|
|
|
|
start: number;
|
|
|
|
}>;
|
|
|
|
// (undocumented)
|
|
|
|
static setPhysChunk(view: DataView, dpr?: number, options?: BlobPropertyBag): Blob;
|
|
|
|
}
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export function promiseWithResolve<T>(): Promise<T> & {
|
|
|
|
resolve: (value: T) => void;
|
|
|
|
reject: (reason?: any) => void;
|
|
|
|
};
|
|
|
|
|
2023-06-09 11:43:01 +00:00
|
|
|
// @public (undocumented)
|
|
|
|
export type RecursivePartial<T> = {
|
|
|
|
[P in keyof T]?: RecursivePartial<T[P]>;
|
|
|
|
};
|
|
|
|
|
2023-06-12 14:04:14 +00:00
|
|
|
// @internal (undocumented)
|
2023-06-16 10:33:47 +00:00
|
|
|
type Required_2<T, K extends keyof T> = Expand<Omit<T, K> & _Required<Pick<T, K>>>;
|
2023-06-12 14:04:14 +00:00
|
|
|
export { Required_2 as Required }
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// @public (undocumented)
|
|
|
|
export type Result<T, E> = ErrorResult<E> | OkResult<T>;
|
|
|
|
|
|
|
|
// @public (undocumented)
|
|
|
|
export const Result: {
|
|
|
|
ok<T>(value: T): OkResult<T>;
|
|
|
|
err<E>(error: E): ErrorResult<E>;
|
|
|
|
};
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function rng(seed?: string): () => number;
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function rotateArray<T>(arr: T[], offset: number): T[];
|
|
|
|
|
2024-03-04 16:15:20 +00:00
|
|
|
// @internal
|
|
|
|
export function setInLocalStorage(key: string, value: string): void;
|
|
|
|
|
|
|
|
// @internal
|
|
|
|
export function setInSessionStorage(key: string, value: string): void;
|
|
|
|
|
2023-05-22 08:18:01 +00:00
|
|
|
// @public (undocumented)
|
|
|
|
export function sortById<T extends {
|
|
|
|
id: any;
|
|
|
|
}>(a: T, b: T): -1 | 1;
|
|
|
|
|
2024-02-14 17:53:30 +00:00
|
|
|
// @public
|
|
|
|
export function sortByIndex<T extends {
|
|
|
|
index: IndexKey;
|
|
|
|
}>(a: T, b: T): -1 | 0 | 1;
|
|
|
|
|
use native structuredClone on node, cloudflare workers, and in tests (#3166)
Currently, we only use native `structuredClone` in the browser, falling
back to `JSON.parse(JSON.stringify(...))` elsewhere, despite Node
supporting `structuredClone` [since
v17](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone)
and Cloudflare Workers supporting it [since
2022](https://blog.cloudflare.com/standards-compliant-workers-api/).
This PR adjusts our shim to use the native `structuredClone` on all
platforms, if available.
Additionally, `jsdom` doesn't implement `structuredClone`, a bug [open
since 2022](https://github.com/jsdom/jsdom/issues/3363). This PR patches
`jsdom` environment in all packages/apps that use it for tests.
Also includes a driveby removal of `deepCopy`, a function that is
strictly inferior to `structuredClone`.
### Change Type
<!-- ❗ Please select a 'Scope' label ❗️ -->
- [x] `sdk` — Changes the tldraw SDK
- [x] `dotcom` — Changes the tldraw.com web app
- [ ] `docs` — Changes to the documentation, examples, or templates.
- [ ] `vs code` — Changes to the vscode plugin
- [ ] `internal` — Does not affect user-facing stuff
<!-- ❗ Please select a 'Type' label ❗️ -->
- [ ] `bugfix` — Bug fix
- [ ] `feature` — New feature
- [x] `improvement` — Improving existing features
- [x] `chore` — Updating dependencies, other boring stuff
- [ ] `galaxy brain` — Architectural changes
- [ ] `tests` — Changes to any test code
- [ ] `tools` — Changes to infrastructure, CI, internal scripts,
debugging tools, etc.
- [ ] `dunno` — I don't know
### Test Plan
1. A smoke test would be enough
- [ ] Unit Tests
- [x] End to end tests
2024-03-18 17:16:09 +00:00
|
|
|
// @internal
|
|
|
|
export const STRUCTURED_CLONE_OBJECT_PROTOTYPE: any;
|
|
|
|
|
2024-02-24 20:02:17 +00:00
|
|
|
// @public
|
2023-04-25 11:01:25 +00:00
|
|
|
const structuredClone_2: <T>(i: T) => T;
|
|
|
|
export { structuredClone_2 as structuredClone }
|
|
|
|
|
|
|
|
// @public
|
|
|
|
export function throttle<T extends (...args: any) => any>(func: T, limit: number): (...args: Parameters<T>) => ReturnType<T>;
|
|
|
|
|
2023-05-12 09:43:51 +00:00
|
|
|
// @internal
|
2024-03-18 16:03:44 +00:00
|
|
|
export function throttleToNextFrame(fn: () => void): () => void;
|
2023-05-12 09:43:51 +00:00
|
|
|
|
2024-02-14 17:53:30 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export function validateIndexKey(key: string): asserts key is IndexKey;
|
|
|
|
|
2023-11-16 15:34:56 +00:00
|
|
|
// @internal (undocumented)
|
|
|
|
export function warnDeprecatedGetter(name: string): void;
|
|
|
|
|
2024-02-14 17:53:30 +00:00
|
|
|
// @public
|
|
|
|
export const ZERO_INDEX_KEY: IndexKey;
|
|
|
|
|
2023-04-25 11:01:25 +00:00
|
|
|
// (No @packageDocumentation comment for this package)
|
|
|
|
|
|
|
|
```
|