refactor(parser): wrapper type for parser (#2339)

Split parser into public interface `Parser` and internal implementation `ParserImpl`.

This involves no changes to public API.

This change is a bit annoying, but justification is that it's required for #2341, which I believe to be very worthwhile.

The `ParserOptions` type also makes it a bit clearer what the defaults for `allow_return_outside_function` and `preserve_parens` are. It came as a surprise to me that `preserve_parens` defaults to `true`, and this refactor makes that a bit more obvious when reading the code.

All the real changes are in [oxc_parser/src/lib.rs](https://github.com/oxc-project/oxc/pull/2339/files#diff-8e59dfd35fc50b6ac9a9ccd991e25c8b5d30826e006d565a2e01f3d15dc5f7cb). The rest of the diff is basically replacing `Parser` with `ParserImpl` everywhere else.

crates/oxc_parser/src/cursor.rs

@@ -7,7 +7,7 @@ use oxc_span::Span;
 use crate::{
     diagnostics,
     lexer::{Kind, LexerCheckpoint, LexerContext, Token},
-    Context, Parser,
+    Context, ParserImpl,
 };
 
 #[derive(Clone, Copy)]
@@ -18,7 +18,7 @@ pub struct ParserCheckpoint<'a> {
     errors_pos: usize,
 }
 
-impl<'a> Parser<'a> {
+impl<'a> ParserImpl<'a> {
     pub(crate) fn start_span(&self) -> Span {
         let token = self.cur_token();
         Span::new(token.start, 0)
@@ -266,7 +266,7 @@ impl<'a> Parser<'a> {
     /// # Errors
     pub(crate) fn try_parse<T>(
         &mut self,
-        func: impl FnOnce(&mut Parser<'a>) -> Result<T>,
+        func: impl FnOnce(&mut ParserImpl<'a>) -> Result<T>,
     ) -> Result<T> {
         let checkpoint = self.checkpoint();
         let ctx = self.ctx;
@@ -278,7 +278,7 @@ impl<'a> Parser<'a> {
         result
     }
 
-    pub(crate) fn lookahead<U>(&mut self, predicate: impl Fn(&mut Parser<'a>) -> U) -> U {
+    pub(crate) fn lookahead<U>(&mut self, predicate: impl Fn(&mut ParserImpl<'a>) -> U) -> U {
         let checkpoint = self.checkpoint();
         let answer = predicate(self);
         self.rewind(checkpoint);

crates/oxc_parser/src/js/binding.rs

@@ -4,9 +4,9 @@ use oxc_diagnostics::Result;
 use oxc_span::Span;
 
 use super::list::{ArrayPatternList, ObjectPatternProperties};
-use crate::{diagnostics, lexer::Kind, list::SeparatedList, Context, Parser};
+use crate::{diagnostics, lexer::Kind, list::SeparatedList, Context, ParserImpl};
 
-impl<'a> Parser<'a> {
+impl<'a> ParserImpl<'a> {
     /// Destructuring Binding Patterns
     /// `LexicalBinding`
     ///     `BindingIdentifier` `Initializer_opt`

crates/oxc_parser/src/js/class.rs

@@ -4,15 +4,15 @@ use oxc_diagnostics::Result;
 use oxc_span::{GetSpan, Span};
 
 use super::list::ClassElements;
-use crate::{diagnostics, lexer::Kind, list::NormalList, Parser, StatementContext};
+use crate::{diagnostics, lexer::Kind, list::NormalList, ParserImpl, StatementContext};
 
 type Extends<'a> =
     Vec<'a, (Expression<'a>, Option<Box<'a, TSTypeParameterInstantiation<'a>>>, Span)>;
 
 type Implements<'a> = Vec<'a, Box<'a, TSClassImplements<'a>>>;
 
 /// Section 15.7 Class Definitions
-impl<'a> Parser<'a> {
+impl<'a> ParserImpl<'a> {
     // `start_span` points at the start of all decoractors and `class` keyword.
     pub(crate) fn parse_class_statement(
         &mut self,

crates/oxc_parser/src/js/declaration.rs

@@ -3,7 +3,7 @@ use oxc_ast::ast::*;
 use oxc_diagnostics::Result;
 use oxc_span::{GetSpan, Span};
 
-use crate::{diagnostics, lexer::Kind, Parser, StatementContext};
+use crate::{diagnostics, lexer::Kind, ParserImpl, StatementContext};
 
 #[derive(Clone, Debug, Copy, Eq, PartialEq)]
 pub enum VariableDeclarationParent {
@@ -23,7 +23,7 @@ impl VariableDeclarationContext {
     }
 }
 
-impl<'a> Parser<'a> {
+impl<'a> ParserImpl<'a> {
     pub(crate) fn parse_let(&mut self, stmt_ctx: StatementContext) -> Result<Statement<'a>> {
         let span = self.start_span();
         let peeked = self.peek_kind();

crates/oxc_parser/src/js/expression.rs

@@ -19,10 +19,10 @@ use crate::{
     diagnostics,
     lexer::{parse_big_int, parse_float, parse_int, Kind},
     list::SeparatedList,
-    Context, Parser,
+    Context, ParserImpl,
 };
 
-impl<'a> Parser<'a> {
+impl<'a> ParserImpl<'a> {
     pub(crate) fn parse_paren_expression(&mut self) -> Result<Expression<'a>> {
         self.expect(Kind::LParen)?;
         let expression = self.parse_expression()?;
@@ -977,7 +977,7 @@ impl<'a> Parser<'a> {
                 let pos = self.cur_token().start;
                 if !self.state.not_parenthesized_arrow.contains(&pos) {
                     if let Ok((type_parameters, params, return_type, r#async, span)) =
-                        self.try_parse(Parser::parse_parenthesized_arrow_function_head)
+                        self.try_parse(ParserImpl::parse_parenthesized_arrow_function_head)
                     {
                         return self.parse_arrow_function_body(
                             span,

crates/oxc_parser/src/js/function.rs

@@ -6,7 +6,7 @@ use oxc_diagnostics::Result;
 use oxc_span::{GetSpan, Span};
 
 use super::list::FormalParameterList;
-use crate::{diagnostics, lexer::Kind, list::SeparatedList, Context, Parser, StatementContext};
+use crate::{diagnostics, lexer::Kind, list::SeparatedList, Context, ParserImpl, StatementContext};
 
 type ArrowFunctionHead<'a> = (
     Option<Box<'a, TSTypeParameterDeclaration<'a>>>,
@@ -41,7 +41,7 @@ impl FunctionKind {
     }
 }
 
-impl<'a> Parser<'a> {
+impl<'a> ParserImpl<'a> {
     pub(crate) fn at_function_with_async(&mut self) -> bool {
         self.at(Kind::Function)
             || self.at(Kind::Async)

crates/oxc_parser/src/js/grammar.rs

@@ -4,14 +4,14 @@ use oxc_ast::ast::*;
 use oxc_diagnostics::Result;
 use oxc_span::GetSpan;
 
-use crate::{diagnostics, Parser};
+use crate::{diagnostics, ParserImpl};
 
 pub trait CoverGrammar<'a, T>: Sized {
-    fn cover(value: T, p: &mut Parser<'a>) -> Result<Self>;
+    fn cover(value: T, p: &mut ParserImpl<'a>) -> Result<Self>;
 }
 
 impl<'a> CoverGrammar<'a, Expression<'a>> for AssignmentTarget<'a> {
-    fn cover(expr: Expression<'a>, p: &mut Parser<'a>) -> Result<Self> {
+    fn cover(expr: Expression<'a>, p: &mut ParserImpl<'a>) -> Result<Self> {
         match expr {
             Expression::ArrayExpression(array_expr) => {
                 ArrayAssignmentTarget::cover(array_expr.unbox(), p)
@@ -34,7 +34,7 @@ impl<'a> CoverGrammar<'a, Expression<'a>> for AssignmentTarget<'a> {
 
 impl<'a> CoverGrammar<'a, Expression<'a>> for SimpleAssignmentTarget<'a> {
     #[allow(clippy::only_used_in_recursion)]
-    fn cover(expr: Expression<'a>, p: &mut Parser<'a>) -> Result<Self> {
+    fn cover(expr: Expression<'a>, p: &mut ParserImpl<'a>) -> Result<Self> {
         match expr {
             Expression::Identifier(ident) => {
                 Ok(SimpleAssignmentTarget::AssignmentTargetIdentifier(ident))
@@ -65,7 +65,7 @@ impl<'a> CoverGrammar<'a, Expression<'a>> for SimpleAssignmentTarget<'a> {
 }
 
 impl<'a> CoverGrammar<'a, ArrayExpression<'a>> for ArrayAssignmentTarget<'a> {
-    fn cover(expr: ArrayExpression<'a>, p: &mut Parser<'a>) -> Result<Self> {
+    fn cover(expr: ArrayExpression<'a>, p: &mut ParserImpl<'a>) -> Result<Self> {
         let mut elements = p.ast.new_vec();
         let mut rest = None;
 
@@ -100,7 +100,7 @@ impl<'a> CoverGrammar<'a, ArrayExpression<'a>> for ArrayAssignmentTarget<'a> {
 }
 
 impl<'a> CoverGrammar<'a, Expression<'a>> for AssignmentTargetMaybeDefault<'a> {
-    fn cover(expr: Expression<'a>, p: &mut Parser<'a>) -> Result<Self> {
+    fn cover(expr: Expression<'a>, p: &mut ParserImpl<'a>) -> Result<Self> {
         match expr {
             Expression::AssignmentExpression(assignment_expr) => {
                 let target = AssignmentTargetWithDefault::cover(assignment_expr.unbox(), p)?;
@@ -115,13 +115,13 @@ impl<'a> CoverGrammar<'a, Expression<'a>> for AssignmentTargetMaybeDefault<'a> {
 }
 
 impl<'a> CoverGrammar<'a, AssignmentExpression<'a>> for AssignmentTargetWithDefault<'a> {
-    fn cover(expr: AssignmentExpression<'a>, _p: &mut Parser<'a>) -> Result<Self> {
+    fn cover(expr: AssignmentExpression<'a>, _p: &mut ParserImpl<'a>) -> Result<Self> {
         Ok(Self { span: expr.span, binding: expr.left, init: expr.right })
     }
 }
 
 impl<'a> CoverGrammar<'a, ObjectExpression<'a>> for ObjectAssignmentTarget<'a> {
-    fn cover(expr: ObjectExpression<'a>, p: &mut Parser<'a>) -> Result<Self> {
+    fn cover(expr: ObjectExpression<'a>, p: &mut ParserImpl<'a>) -> Result<Self> {
         let mut properties = p.ast.new_vec();
         let mut rest = None;
 
@@ -147,7 +147,7 @@ impl<'a> CoverGrammar<'a, ObjectExpression<'a>> for ObjectAssignmentTarget<'a> {
 }
 
 impl<'a> CoverGrammar<'a, ObjectProperty<'a>> for AssignmentTargetProperty<'a> {
-    fn cover(property: ObjectProperty<'a>, p: &mut Parser<'a>) -> Result<Self> {
+    fn cover(property: ObjectProperty<'a>, p: &mut ParserImpl<'a>) -> Result<Self> {
         if property.shorthand {
             let binding = match property.key {
                 PropertyKey::Identifier(ident) => {