@yorkie-js/sdk 0.6.41-rc → 0.6.41-rc3

package/dist/yorkie-js-sdk.d.ts

@@ -2328,8 +2328,10 @@ declare const _default: {
     Text: typeof Text_2;
     Counter: typeof Counter;
     Tree: typeof Tree;
+    Devtools: typeof Devtools;
     Channel: typeof Channel;
     ChannelEventType: typeof ChannelEventType;
+    YSON: typeof YSON;
     LogLevel: typeof LogLevel;
     setLogLevel: typeof setLogLevel;
     IntType: CounterType;
@@ -3498,6 +3500,42 @@ declare interface InitializedEvent_2<P extends Indexable_2> extends BaseDocEvent
     value: Array<{ clientID: ActorID_2; presence: P }>;
 }
 
+/**
+ * `isBinData` checks if a value is a YSONBinData object.
+ */
+declare function isBinData(value: any): value is YSONBinData {
+    return (
+    typeof value === 'object' &&
+    value !== null &&
+    value.type === 'BinData' &&
+    typeof value.value === 'string'
+    );
+}
+
+/**
+ * `isCounter` checks if a value is a YSONCounter object.
+ */
+declare function isCounter(value: any): value is YSONCounter {
+    return (
+    typeof value === 'object' &&
+    value !== null &&
+    value.type === 'Counter' &&
+    typeof value.value === 'object'
+    );
+}
+
+/**
+ * `isDate` checks if a value is a YSONDate object.
+ */
+declare function isDate(value: any): value is YSONDate {
+    return (
+    typeof value === 'object' &&
+    value !== null &&
+    value.type === 'Date' &&
+    typeof value.value === 'string'
+    );
+}
+
 /**
  * `isDocEventForReplay` checks if an event can be used to replay a document.
  */
@@ -3527,6 +3565,72 @@ events: Array<DocEvent_2>,
     return events.every(isDocEventForReplay);
 }
 
+/**
+ * `isInt` checks if a value is a YSONInt object.
+ */
+declare function isInt(value: any): value is YSONInt {
+    return (
+    typeof value === 'object' &&
+    value !== null &&
+    value.type === 'Int' &&
+    typeof value.value === 'number'
+    );
+}
+
+/**
+ * `isLong` checks if a value is a YSONLong object.
+ */
+declare function isLong(value: any): value is YSONLong {
+    return (
+    typeof value === 'object' &&
+    value !== null &&
+    value.type === 'Long' &&
+    typeof value.value === 'number'
+    );
+}
+
+/**
+ * `isObject` checks if a value is a plain YSON object (not a special type).
+ */
+declare function isObject(value: any): value is { [key: string]: YSONValue } {
+    return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !isText(value) &&
+    !isTree(value) &&
+    !isInt(value) &&
+    !isLong(value) &&
+    !isDate(value) &&
+    !isBinData(value) &&
+    !isCounter(value)
+    );
+}
+
+/**
+ * `isText` checks if a value is a YSONText object.
+ */
+declare function isText(value: any): value is YSONText {
+    return (
+    typeof value === 'object' &&
+    value !== null &&
+    value.type === 'Text' &&
+    Array.isArray(value.nodes)
+    );
+}
+
+/**
+ * `isTree` checks if a value is a YSONTree object.
+ */
+declare function isTree(value: any): value is YSONTree {
+    return (
+    typeof value === 'object' &&
+    value !== null &&
+    value.type === 'Tree' &&
+    typeof value.root === 'object'
+    );
+}
+
 /**
  * `Json` represents the JSON data type. It is used to represent the data
  * structure of the document.
@@ -4414,6 +4518,46 @@ export declare type PanelToSDKMessage =
     docKey: string;
 };
 
+/**
+ * `parse` parses a YSON string into a typed JavaScript object.
+ *
+ * YSON extends JSON to support Yorkie CRDT types:
+ * - `Text([...])` for Text CRDT
+ * - `Tree(...)` for Tree CRDT
+ * - Standard JSON for primitives, objects, and arrays
+ *
+ * @param yson - YSON formatted string
+ * @returns Parsed YSONValue
+ * @throws YorkieError if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const data = parse('{"content":Text([{"val":"Hi"}])}');
+ * // { content: { type: 'Text', nodes: [{ val: 'Hi' }] } }
+ *
+ * // With type parameter:
+ * const data = parse<{ content: YSONText }>('{"content":Text([{"val":"Hi"}])}');
+ * // data.content is now typed as YSONText
+ * ```
+ */
+declare function parse<T = YSONValue>(yson: string): T {
+    try {
+        // Preprocess YSON string to handle special types
+        const processed = preprocessYSON(yson);
+
+        // Parse as JSON
+        const parsed = JSON.parse(processed);
+
+        // Post-process to restore type information
+        return postprocessValue(parsed) as T;
+    } catch (err) {
+        throw new YorkieError(
+        Code.ErrInvalidArgument,
+        `Failed to parse YSON: ${err instanceof Error ? err.message : String(err)}`,
+        );
+    }
+}
+
 /**
  * `PathOf` represents the type of all possible paths in the Document.subscribe.
  */
@@ -4733,8 +4877,14 @@ export declare interface RevisionSummary {
      */
     description: string;
     /**
-     * `snapshot` is the serialized document content (JSON format) at this revision point.
-     * This contains only the pure data without CRDT metadata.
+     * `snapshot` is the serialized document content in YSON format at this revision point.
+     *
+     * Use `YSON.parse()` to convert this string to a typed JavaScript object:
+     *
+     * ```javascript
+     * import { YSON } from 'yorkie-js-sdk';
+     * const snapshot = YSON.parse(revision.snapshot);
+     * ```
      */
     snapshot: string;
     /**
@@ -5804,6 +5954,22 @@ export declare type TextPosStruct = {
  */
 export declare type TextPosStructRange = [TextPosStruct, TextPosStruct];
 
+/**
+ * `textToString` extracts plain text content from YSONText.
+ *
+ * @param text - YSONText object
+ * @returns Plain text string
+ *
+ * @example
+ * ```typescript
+ * const text = { type: 'Text', nodes: [{val: 'H'}, {val: 'i'}] };
+ * textToString(text); // "Hi"
+ * ```
+ */
+declare function textToString(text: YSONText): string {
+    return text.nodes.map((node) => node.val).join('');
+}
+
 /**
  * `TextValueType` is a value of Text
  * which has a attributes that expresses the text style.
@@ -6367,6 +6533,16 @@ declare type TreeStyleOpInfo_2 = {
  */
 declare type TreeToken<T> = [T, TokenType];
 
+/**
+ * `treeToXML` converts YSONTree to XML string representation.
+ *
+ * @param tree - YSONTree object
+ * @returns XML string
+ */
+declare function treeToXML(tree: YSONTree): string {
+    return treeNodeToXML(tree.root);
+}
+
 export declare type Unsubscribe = () => void;
 
 export declare interface UnwatchedEvent<P extends Indexable> extends BaseDocEvent_2 {
@@ -6577,4 +6753,209 @@ declare interface WatchedEvent_2<P extends Indexable_2> extends BaseDocEvent {
  */
 export declare type WrappedElement<T = unknown, A extends Indexable = Indexable> = Primitive | JSONObject<T> | JSONArray<T> | Text_2<A> | Counter | Tree;
 
+declare namespace YSON {
+    export {
+        YSONValue,
+        YSONText as Text,
+        YSONTree as Tree,
+        YSONTextNode as TextNode,
+        YSONTreeNode as TreeNode,
+        YSONInt as Int,
+        YSONLong as Long,
+        YSONDate as Date,
+        YSONBinData as BinData,
+        YSONCounter as Counter,
+        isText,
+        isTree,
+        isInt,
+        isLong,
+        isDate,
+        isBinData,
+        isCounter,
+        isObject,
+        parse,
+        textToString,
+        treeToXML
+    }
+}
+export { YSON }
+
+/**
+ * `YSONBinData` represents Base64-encoded binary data.
+ *
+ * @example
+ * ```typescript
+ * { type: 'BinData', value: 'AQID' }
+ * ```
+ */
+declare interface YSONBinData {
+    type: 'BinData';
+    value: string;
+}
+
+/**
+ * `YSONCounter` represents a Counter CRDT for collaborative counting.
+ *
+ * @example
+ * ```typescript
+ * { type: 'Counter', value: { type: 'Int', value: 10 } }
+ * ```
+ */
+declare interface YSONCounter {
+    type: 'Counter';
+    value: YSONInt | YSONLong;
+}
+
+/**
+ * `YSONDate` represents an ISO 8601 timestamp.
+ *
+ * @example
+ * ```typescript
+ * { type: 'Date', value: '2025-01-02T15:04:05.058Z' }
+ * ```
+ */
+declare interface YSONDate {
+    type: 'Date';
+    value: string;
+}
+
+/**
+ * `YSONInt` represents a 32-bit integer.
+ *
+ * @example
+ * ```typescript
+ * { type: 'Int', value: 42 }
+ * ```
+ */
+declare interface YSONInt {
+    type: 'Int';
+    value: number;
+}
+
+/**
+ * `YSONLong` represents a 64-bit integer.
+ *
+ * @example
+ * ```typescript
+ * { type: 'Long', value: 64 }
+ * ```
+ */
+declare interface YSONLong {
+    type: 'Long';
+    value: number;
+}
+
+/**
+ * `YSONText` represents a Text CRDT structure.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'Text',
+ *   nodes: [
+ *     { val: 'H' },
+ *     { val: 'i' }
+ *   ]
+ * }
+ * ```
+ */
+declare interface YSONText {
+    type: 'Text';
+    nodes: Array<YSONTextNode>;
+}
+
+/**
+ * `YSONTextNode` represents a single character in a Text CRDT.
+ *
+ * @example
+ * ```typescript
+ * { val: 'H', attrs: { bold: true } }
+ * ```
+ */
+declare interface YSONTextNode {
+    /**
+     * The character value
+     */
+    val: string;
+
+    /**
+     * Optional attributes (e.g., formatting)
+     */
+    attrs?: Record<string, any>;
+}
+
+/**
+ * `YSONTree` represents a Tree CRDT structure.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   type: 'Tree',
+ *   root: {
+ *     type: 'doc',
+ *     children: [
+ *       { type: 'p', children: [{ type: 'text', value: 'Hello' }] }
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+declare interface YSONTree {
+    type: 'Tree';
+    root: YSONTreeNode;
+}
+
+/**
+ * `YSONTreeNode` represents a node in a Tree CRDT.
+ *
+ * For text nodes: `{ type: 'text', value: 'content' }`
+ * For element nodes: `{ type: 'p', children: [...] }`
+ */
+declare interface YSONTreeNode {
+    /**
+     * Node type (e.g., 'text', 'p', 'div')
+     */
+    type: string;
+
+    /**
+     * Text content (for text nodes)
+     */
+    value?: string;
+
+    /**
+     * Attributes (for element nodes)
+     */
+    attrs?: Record<string, string>;
+
+    /**
+     * Child nodes (for element nodes)
+     */
+    children?: Array<YSONTreeNode>;
+}
+
+/**
+ * `YSONValue` represents any valid YSON value.
+ *
+ * Can be:
+ * - Primitives: string, number, boolean, null
+ * - Collections: arrays, objects
+ * - CRDT types: Text, Tree, Counter
+ * - Special types: Int, Long, Date, BinData
+ */
+declare type YSONValue =
+| string
+| number
+| boolean
+// eslint-disable-next-line @typescript-eslint/no-restricted-types
+| null
+| YSONText
+| YSONTree
+| YSONInt
+| YSONLong
+| YSONDate
+| YSONBinData
+| YSONCounter
+| { [key: string]: YSONValue }
+| Array<YSONValue>;
+
 export { }