object-input-stream 0.1.0 → 0.2.0

package/README.md

@@ -98,9 +98,9 @@ class CustomSerializable implements Serializable {
 ois.registerSerializable("com.mypackage.CustomSerializable", CustomSerializable);
 ```
 
-> Note: if you recreate and register an entire inheritence chain of serializable classes, their `readObject` methods will be called in order, same as in Java. For every class in the chain that doesn't have a JavaScript handler / where the handler class doesn't have a `readObject` method, `ois.defaultReadObject` is called, again, same as in Java.
+> Warning: Java serializable classes that don't write their fields before writing anything else to stream MUST have a custom handler class that replicates that behavior. Not doing that could lead to undefined behavior.
 
-> Warning: Java serializable classes that write their fields before writing anything else to stream MUST have a custom handler class that replicates this behavior. Not doing that would lead to undefined behavior.
+> Note: if you recreate and register an entire inheritence chain of serializable classes, their `readObject` methods will be called in order, same as in Java. For every class in the chain that doesn't have a JavaScript handler / where the handler class doesn't have a `readObject` method, `ois.defaultReadObject` is called, again, same as in Java.
 
 ##### Externalizable Classes
 
@@ -122,7 +122,7 @@ class CustomExternalizable implements Externalizable {
 ois.registerExternalizable("com.mypackage.CustomExternalizable", CustomExternalizable);
 ```
 
-> Warning: Java externalizable objects written using `PROTOCOL_VERSION_1` MUST have a custom handler class that reads all written data to stream. Not doing that would lead to undefined behavior.
+> Warning: Java externalizable objects written using `PROTOCOL_VERSION_1` MUST have a custom handler class that reads all written data to stream. Not doing that could lead to undefined behavior.
 
 ##### Enum Objects
 
@@ -223,7 +223,7 @@ Dynamically generated general class handlers are of the following structure:
 ```ts
 class ExampleProxy {
     // A list of the proxy interface names associated with the class
-    static readonly proxyInterfaces: string[] = []
+    static readonly $proxyInterfaces: string[] = []
     // The proxy handler class / lambda from Java
     h?: InvocationHandler
     // Creates a proxy object that calls this.h on property access
@@ -235,6 +235,8 @@ interface InvocationHandler {
 }
 ```
 
+To use a proxy object in JavaScript, you will need to register a class to correspond to its handler's class.
+
 #### Built-in Class Handlers
 
 Primitive wrapper types have built-in handler classes that implement `readResolve` to replace instances with their primitive values. E.g. if the next object on stream is an `Integer` of value 5 and you call `readObject`, it will return the primitive value `5`.
@@ -283,21 +285,21 @@ type OisOptions = {
 ## AST
 
 ```js
-// TODO
+import { ObjectInputStreamAST } from 'object-input-stream';
+
+const data = new Uint8Array( /* Java object serialization stream data */ );
+const ois = new ObjectInputStream(data);
+
+// Read everything
+
+const ast = ois.getAST();
 ```
 
+> WARNING: The AST structure and API are unstable, and may change at any time.
+
+> Note: an AST can be reliably produced only for a stream that has been parsed fully and without errors.
+
 ## Limitations
 
 - Requires a runtime that supports `bigint` (all modern runtimes)
 - Doesn't support strings over 9 petabytes in size (`Number.MAX_SAFE_INTEGER` bytes)
-
-## TODO
-
-- [ ] ObjectInputStreamAST class: emit AST after parsing
-- [ ] Complete existing tests
-- [ ] Expand tests
-    - [ ] Classes
-    - [ ] Class descriptors
-    - [ ] Proxy classes
-    - [ ] Enums
-    - [ ] Sudden death: a brazillian randomly generated primitives and objects with a complex reference graph and readObject/readExternal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "object-input-stream",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "ObjectInputStream for JavaScript. Read Java serialized objects in Node and the browser.",
   "main": "dist/index.js",
   "types": "dist/index.d.js",
@@ -34,6 +34,7 @@
     "cross-env": "^10.1.0",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   }
 }

package/src/ast.ts

@@ -22,8 +22,10 @@ export default Ast
 export type Node =
     RootNode | MagicNode | VersionNode | ContentsNode
   | BlockDataSequenceNode | BlockDataNode
-  | PrimitiveNode | UtfNode | LongUtfNode | UtfBodyNode | BytesNode | SkippedNode
+  | PrimitiveNode | UtfNode | LongUtfNode | UtfBodyNode
   | ObjectNode | TCNode | ClassDescInfoNode | ProxyClassDescInfoNode
+  | SerialDataNode | ExternalDataNode | SerialClassDataNode | FieldsNode | ValuesNode | FieldDescNode
+  | AnnotationNode
 
 export interface RootNode extends BaseNode<[MagicNode, VersionNode, ContentsNode]> {
     type: "root"
@@ -36,7 +38,7 @@ export interface ContentsNode extends BaseNode<(BlockDataSequenceNode | ObjectNo
     type: "contents"
 }
 
-interface BaseNode<C extends BaseNode<any>[] | null> {
+interface BaseNode<C extends Node[] | null> {
     type: string
     span: {start: number, end: number}
     children: C
@@ -46,12 +48,12 @@ interface BaseNode<C extends BaseNode<any>[] | null> {
 
 // ========== Primitives ==========
 
-export type PrimitiveNode = ByteNode | UnsignedByteNode | ShortNode | UnsignedShortNode | IntNode | FloatNode | DoubleNode | CharNode | BooleanNode | LongNode
+export type PrimitiveNode = ByteNode | UnsignedByteNode | ShortNode | UnsignedShortNode | IntNode | FloatNode | DoubleNode | CharNode | BooleanNode | LongNode | BytesNode
 
 interface BasePrimitiveNode extends BaseNode<null> {
     type: "primitive"
     dataType: string
-    value: number | string | boolean | bigint
+    value: number | string | boolean | bigint | null
 }
 interface NumberNode extends BasePrimitiveNode {
     dataType: string
@@ -77,33 +79,30 @@ export interface LongNode extends BasePrimitiveNode {
     dataType: "long"
     value: bigint
 }
+export interface BytesNode extends BasePrimitiveNode {
+    dataType: "bytes"
+    value: null
+}
 
 export interface UtfNode extends BaseNode<[UnsignedShortNode, UtfBodyNode]> {
     type: "utf"
+    value: string
 }
 export interface LongUtfNode extends BaseNode<[LongNode, UtfBodyNode]> {
     type: "long-utf"
+    value: string
 }
 export interface UtfBodyNode extends BaseNode<null> {
     type: "utf-body"
     value: string
 }
 
-export interface BytesNode extends BaseNode<null> {
-    type: "bytes"
-}
-
-export interface SkippedNode extends BaseNode<null> {
-    type: "skipped"
-    reason: string
-}
-
 
 // ========== Block Data ==========
 
-export interface BlockDataSequenceNode extends BaseNode<BlockDataNode[]> {
+export interface BlockDataSequenceNode extends BaseNode<(BlockDataNode | ResetNode)[]> {
     type: "blockdata-sequence"
-    values: (PrimitiveNode | UtfNode | SkippedNode)[]
+    values: (PrimitiveNode | UtfNode)[]
 }
 
 export interface BlockDataNode extends BaseNode<
@@ -119,13 +118,13 @@ export interface BlockDataNode extends BaseNode<
 export type ObjectNode = NewObjectNode | NewClassNode | NewArrayNode | NewStringNode | NewEnumNode | NewClassDescNode | PrevObjectNode | NullNode | ExceptionNode | ResetNode
 export type ClassDescNode = NewClassDescNode | NullNode | PrevObjectNode
 
-interface BaseObjectNode<C extends [TCNode, ...BaseNode<any>[]]> extends BaseNode<C> {
+interface BaseObjectNode<C extends [TCNode, ...Node[]]> extends BaseNode<C> {
     type: "object"
     objectType: string
 }
 
 export interface NewObjectNode extends BaseObjectNode<
-    [TC_OBJECT_Node, ClassDescNode, ...ClassDataNode[]]
+    [TC_OBJECT_Node, ClassDescNode, (ExternalDataNode | SerialDataNode)]
 > {
     objectType: "new-object"
     handle: Handle
@@ -143,9 +142,10 @@ export interface NewStringNode extends BaseObjectNode<
     [TC_LONGSTRING_Node, LongUtfNode]
 > {
     objectType: "new-string"
+    value: string
     handle: Handle
 }
-export interface NewEnumNode extends BaseObjectNode<[TC_ENUM_Node, ClassDescNode, ObjectNode]> {
+export interface NewEnumNode extends BaseObjectNode<[TC_ENUM_Node, ClassDescNode, StringNode]> {
     objectType: "new-enum"
     handle: Handle
 }
@@ -163,7 +163,7 @@ export interface PrevObjectNode extends BaseObjectNode<[TC_REFERENCE_Node, IntNo
 export interface NullNode extends BaseObjectNode<[TC_NULL_Node]> {
     objectType: "null"
 }
-export interface ExceptionNode extends BaseObjectNode<[TC_EXCEPTION_Node, ObjectNode]> {
+export interface ExceptionNode extends BaseObjectNode<[TC_EXCEPTION_Node, (NewObjectNode | PrevObjectNode)]> {
     objectType: "exception"
     exceptionEpoch: number
     newEpoch: number
@@ -173,44 +173,47 @@ export interface ResetNode extends BaseObjectNode<[TC_RESET_Node]> {
     newEpoch: number
 }
 
-export interface ClassDescInfoNode extends BaseNode<[ByteNode, FieldsNode, ContentsNode, TC_ENDBLOCKDATA_Node, ClassDescNode]> {
+export interface ClassDescInfoNode extends BaseNode<[UnsignedByteNode, FieldsNode, AnnotationNode, ClassDescNode]> {
     type: "class-desc-info"
 }
-export interface ProxyClassDescInfoNode extends BaseNode<[IntNode, ...UtfNode[], ContentsNode, TC_ENDBLOCKDATA_Node, ClassDescNode]> {
+export interface ProxyClassDescInfoNode extends BaseNode<[IntNode, ...UtfNode[], AnnotationNode, ClassDescNode]> {
     type: "proxy-class-desc-info"
 }
+export interface AnnotationNode extends BaseNode<[ContentsNode, TC_ENDBLOCKDATA_Node]> {
+    type: "annotation"
+}
 
+export type StringNode = NewStringNode | PrevObjectNode;
 
 // ========== Fields & Values ==========
 
-export type ClassDataNode = NoWrClassNode | WrClassNode | ExternalClassNode | OldExternalClassNode
-
-interface BaseClassDataNode<C extends BaseNode<any>[] | null> extends BaseNode<C> {
-    type: "class-data"
-    classType: string
+export interface SerialDataNode extends BaseNode<SerialClassDataNode[]> {
+    type: "serial-data"
 }
-export interface NoWrClassNode extends BaseClassDataNode<[ValuesNode]> {
-    classType: "serializable"
+export type SerialClassDataNode = NoWrClassNode | WrClassNode;
+export interface NoWrClassNode extends BaseNode<
+    // Compliant signature is [ValuesNode],
+    // but read methods can ignore this constraint
+    [ContentsNode, ...([ValuesNode]|[])]
+> {
+    type: "class-data"
     writeMethod: false
 }
-export interface WrClassNode extends BaseClassDataNode<
-    [ValuesNode, ContentsNode] |
-
-    // A write method can choose to violate the spec and write its values late, or not at all.
-    // Why? Because fuck you that's why.
-    [ContentsNode, ValuesNode, ContentsNode] |
-    [ContentsNode, ValuesNode] |
-    [ContentsNode]
+export interface WrClassNode extends BaseNode<
+    // Compliant signature is [ValuesNode, AnnotationNode],
+    // but read methods can ignore this constraint
+    [...([ContentsNode, ValuesNode]|[]), AnnotationNode]
 > {
-    classType: "serializable"
+    type: "class-data"
     writeMethod: true
 }
-export interface ExternalClassNode extends BaseClassDataNode<[ContentsNode]> {
-    classType: "externalizable"
+export type ExternalDataNode = ExternalClassDataNode | OldExternalClassDataNode;
+export interface ExternalClassDataNode extends BaseNode<[AnnotationNode]> {
+    type: "external-data"
     protocolVersion: 2
 }
-export interface OldExternalClassNode extends BaseClassDataNode<(ObjectNode | PrimitiveNode | UtfNode | BytesNode)[]> {
-    classType: "externalizable"
+export interface OldExternalClassDataNode extends BaseNode<(ObjectNode | PrimitiveNode | UtfNode)[]> {
+    type: "external-data"
     protocolVersion: 1
 }
 
@@ -226,7 +229,7 @@ export interface PrimitiveDescNode extends BaseNode<[UnsignedByteNode, UtfNode]>
     type: "field-desc"
     fieldType: "primitive"
 }
-export interface ObjectDescNode extends BaseNode<[UnsignedByteNode, UtfNode, ObjectNode]> {
+export interface ObjectDescNode extends BaseNode<[UnsignedByteNode, UtfNode, StringNode]> {
     type: "field-desc"
     fieldType: "object"
 }
@@ -239,7 +242,7 @@ interface BaseTCNode extends BaseNode<null> {
     value: number
 }
 
-type TCNode = TC_NULL_Node | TC_REFERENCE_Node | TC_CLASSDESC_Node | TC_OBJECT_Node | TC_STRING_Node | TC_ARRAY_Node | TC_CLASS_Node | TC_BLOCKDATA_Node | TC_ENDBLOCKDATA_Node | TC_RESET_Node | TC_BLOCKDATALONG_Node | TC_EXCEPTION_Node | TC_LONGSTRING_Node | TC_PROXYCLASSDESC_Node | TC_ENUM_Node
+export type TCNode = TC_NULL_Node | TC_REFERENCE_Node | TC_CLASSDESC_Node | TC_OBJECT_Node | TC_STRING_Node | TC_ARRAY_Node | TC_CLASS_Node | TC_BLOCKDATA_Node | TC_ENDBLOCKDATA_Node | TC_RESET_Node | TC_BLOCKDATALONG_Node | TC_EXCEPTION_Node | TC_LONGSTRING_Node | TC_PROXYCLASSDESC_Node | TC_ENUM_Node
 
 export type TC_NULL_Node           = BaseTCNode & {value: typeof ObjectInputStream.TC_NULL}
 export type TC_REFERENCE_Node      = BaseTCNode & {value: typeof ObjectInputStream.TC_REFERENCE}

package/src/index.ts

@@ -13,6 +13,8 @@ export {
     FieldDesc,
 } from './object-input-stream';
 
+export { ObjectInputStreamAST } from './ois-ast';
+
 export * as exceptions from './exceptions';
 export * as ast from './ast';
 export * as classes from './classes';

package/src/internal.ts

@@ -7,4 +7,6 @@ export {
     BaseFallbackSerializable,
     BaseFallbackExternalizable,
     BaseFallbackEnum,
+    ReadMethodT,
+    EnumProxyHandler,
 } from './object-input-stream';