Skip to content

Commit

Permalink
rename pkg
Browse files Browse the repository at this point in the history
  • Loading branch information
devsergiy committed Aug 22, 2024
1 parent b7a31cc commit 14b02b3
Show file tree
Hide file tree
Showing 26 changed files with 94 additions and 90 deletions.
56 changes: 28 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[![Build Status](https://travis-ci.org/valyala/fastjson.svg)](https://travis-ci.org/valyala/fastjson)
[![GoDoc](https://godoc.org/github.com/valyala/fastjson?status.svg)](http://godoc.org/github.com/valyala/fastjson)
[![Go Report](https://goreportcard.com/badge/github.com/valyala/fastjson)](https://goreportcard.com/report/github.com/valyala/fastjson)
[![GoDoc](https://godoc.org/github.com/wundergraph/astjson?status.svg)](http://godoc.org/github.com/wundergraph/astjson)
[![Go Report](https://goreportcard.com/badge/github.com/wundergraph/astjson)](https://goreportcard.com/report/github.com/wundergraph/astjson)
[![codecov](https://codecov.io/gh/valyala/fastjson/branch/master/graph/badge.svg)](https://codecov.io/gh/valyala/fastjson)

# fastjson - fast JSON parser and validator for Go
Expand All @@ -12,28 +12,28 @@
See [benchmarks](#benchmarks).
* Parses arbitrary JSON without schema, reflection, struct magic and code generation
contrary to [easyjson](https://github.com/mailru/easyjson).
* Provides simple [API](http://godoc.org/github.com/valyala/fastjson).
* Provides simple [API](http://godoc.org/github.com/wundergraph/astjson).
* Outperforms [jsonparser](https://github.com/buger/jsonparser) and [gjson](https://github.com/tidwall/gjson)
when accessing multiple unrelated fields, since `fastjson` parses the input JSON only once.
* Validates the parsed JSON unlike [jsonparser](https://github.com/buger/jsonparser)
and [gjson](https://github.com/tidwall/gjson).
* May quickly extract a part of the original JSON with `Value.Get(...).MarshalTo` and modify it
with [Del](https://godoc.org/github.com/valyala/fastjson#Value.Del)
and [Set](https://godoc.org/github.com/valyala/fastjson#Value.Set) functions.
with [Del](https://godoc.org/github.com/wundergraph/astjson#Value.Del)
and [Set](https://godoc.org/github.com/wundergraph/astjson#Value.Set) functions.
* May parse array containing values with distinct types (aka non-homogenous types).
For instance, `fastjson` easily parses the following JSON array `[123, "foo", [456], {"k": "v"}, null]`.
* `fastjson` preserves the original order of object items when calling
[Object.Visit](https://godoc.org/github.com/valyala/fastjson#Object.Visit).
[Object.Visit](https://godoc.org/github.com/wundergraph/astjson#Object.Visit).


## Known limitations

* Requies extra care to work with - references to certain objects recursively
returned by [Parser](https://godoc.org/github.com/valyala/fastjson#Parser)
must be released before the next call to [Parse](https://godoc.org/github.com/valyala/fastjson#Parser.Parse).
Otherwise the program may work improperly. The same applies to objects returned by [Arena](https://godoc.org/github.com/valyala/fastjson#Arena).
Adhere recommendations from [docs](https://godoc.org/github.com/valyala/fastjson).
* Cannot parse JSON from `io.Reader`. There is [Scanner](https://godoc.org/github.com/valyala/fastjson#Scanner)
returned by [Parser](https://godoc.org/github.com/wundergraph/astjson#Parser)
must be released before the next call to [Parse](https://godoc.org/github.com/wundergraph/astjson#Parser.Parse).
Otherwise the program may work improperly. The same applies to objects returned by [Arena](https://godoc.org/github.com/wundergraph/astjson#Arena).
Adhere recommendations from [docs](https://godoc.org/github.com/wundergraph/astjson).
* Cannot parse JSON from `io.Reader`. There is [Scanner](https://godoc.org/github.com/wundergraph/astjson#Scanner)
for parsing stream of JSON values from a string.


Expand Down Expand Up @@ -75,7 +75,7 @@ Accessing multiple fields with error handling:
// arr.1=foo
```

See also [examples](https://godoc.org/github.com/valyala/fastjson#pkg-examples).
See also [examples](https://godoc.org/github.com/wundergraph/astjson#pkg-examples).


## Security
Expand All @@ -89,17 +89,17 @@ See also [examples](https://godoc.org/github.com/valyala/fastjson#pkg-examples).

## Performance optimization tips

* Re-use [Parser](https://godoc.org/github.com/valyala/fastjson#Parser) and [Scanner](https://godoc.org/github.com/valyala/fastjson#Scanner)
* Re-use [Parser](https://godoc.org/github.com/wundergraph/astjson#Parser) and [Scanner](https://godoc.org/github.com/wundergraph/astjson#Scanner)
for parsing many JSONs. This reduces memory allocations overhead.
[ParserPool](https://godoc.org/github.com/valyala/fastjson#ParserPool) may be useful in this case.
* Prefer calling `Value.Get*` on the value returned from [Parser](https://godoc.org/github.com/valyala/fastjson#Parser)
[ParserPool](https://godoc.org/github.com/wundergraph/astjson#ParserPool) may be useful in this case.
* Prefer calling `Value.Get*` on the value returned from [Parser](https://godoc.org/github.com/wundergraph/astjson#Parser)
instead of calling `Get*` one-liners when multiple fields
must be obtained from JSON, since each `Get*` one-liner re-parses
the input JSON again.
* Prefer calling once [Value.Get](https://godoc.org/github.com/valyala/fastjson#Value.Get)
* Prefer calling once [Value.Get](https://godoc.org/github.com/wundergraph/astjson#Value.Get)
for common prefix paths and then calling `Value.Get*` on the returned value
for distinct suffix paths.
* Prefer iterating over array returned from [Value.GetArray](https://godoc.org/github.com/valyala/fastjson#Object.Visit)
* Prefer iterating over array returned from [Value.GetArray](https://godoc.org/github.com/wundergraph/astjson#Object.Visit)
with a range loop instead of calling `Value.Get*` for each array item.

## Fuzzing
Expand All @@ -114,8 +114,8 @@ Build using `go-fuzz-build` and run `go-fuzz` with an optional corpus.
```bash
mkdir -p workdir/corpus
cp $GOPATH/src/github.com/dvyukov/go-fuzz-corpus/json/corpus/* workdir/corpus
go-fuzz-build github.com/valyala/fastjson
go-fuzz -bin=fastjson-fuzz.zip -workdir=workdir
go-fuzz-build github.com/wundergraph/astjson
go-fuzz -bin=astjson-fuzz.zip -workdir=workdir
```

## Benchmarks
Expand All @@ -141,10 +141,10 @@ Legend:
* `fastjson-get` - parse using `fastjson` with fields access similar to `stdjson-struct`.

```
$ GOMAXPROCS=1 go test github.com/valyala/fastjson -bench='Parse$'
$ GOMAXPROCS=1 go test github.com/wundergraph/astjson -bench='Parse$'
goos: linux
goarch: amd64
pkg: github.com/valyala/fastjson
pkg: github.com/wundergraph/astjson
BenchmarkParse/small/stdjson-map 200000 7305 ns/op 26.01 MB/s 960 B/op 51 allocs/op
BenchmarkParse/small/stdjson-struct 500000 3431 ns/op 55.37 MB/s 224 B/op 4 allocs/op
BenchmarkParse/small/stdjson-empty-struct 500000 2273 ns/op 83.58 MB/s 168 B/op 2 allocs/op
Expand Down Expand Up @@ -180,10 +180,10 @@ BenchmarkParse/twitter/fastjson-get 2000 777833 ns/op 81
Benchmark results for json validation:

```
$ GOMAXPROCS=1 go test github.com/valyala/fastjson -bench='Validate$'
$ GOMAXPROCS=1 go test github.com/wundergraph/astjson -bench='Validate$'
goos: linux
goarch: amd64
pkg: github.com/valyala/fastjson
pkg: github.com/wundergraph/astjson
BenchmarkValidate/small/stdjson 2000000 955 ns/op 198.83 MB/s 72 B/op 2 allocs/op
BenchmarkValidate/small/fastjson 5000000 384 ns/op 493.60 MB/s 0 B/op 0 allocs/op
BenchmarkValidate/medium/stdjson 200000 10799 ns/op 215.66 MB/s 184 B/op 5 allocs/op
Expand All @@ -204,24 +204,24 @@ BenchmarkValidate/twitter/fastjson 2000 1036796 ns/op 609.10 MB/s
A: Because other packages require either rigid JSON schema via struct magic
and code generation or perform poorly when multiple unrelated fields
must be obtained from the parsed JSON.
Additionally, `fastjson` provides nicer [API](http://godoc.org/github.com/valyala/fastjson).
Additionally, `fastjson` provides nicer [API](http://godoc.org/github.com/wundergraph/astjson).

* Q: _What is the main purpose for `fastjson`?_
A: High-perf JSON parsing for [RTB](https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf)
and other [JSON-RPC](https://en.wikipedia.org/wiki/JSON-RPC) services.

* Q: _Why fastjson doesn't provide fast marshaling (serialization)?_
A: Actually it provides some sort of marshaling - see [Value.MarshalTo](https://godoc.org/github.com/valyala/fastjson#Value.MarshalTo).
A: Actually it provides some sort of marshaling - see [Value.MarshalTo](https://godoc.org/github.com/wundergraph/astjson#Value.MarshalTo).
But I'd recommend using [quicktemplate](https://github.com/valyala/quicktemplate#use-cases)
for high-performance JSON marshaling :)

* Q: _`fastjson` crashes my program!_
A: There is high probability of improper use.
* Make sure you don't hold references to objects recursively returned by `Parser` / `Scanner`
beyond the next `Parser.Parse` / `Scanner.Next` call
if such restriction is mentioned in [docs](https://github.com/valyala/fastjson/issues/new).
if such restriction is mentioned in [docs](https://github.com/wundergraph/astjson/issues/new).
* Make sure you don't access `fastjson` objects from concurrently running goroutines
if such restriction is mentioned in [docs](https://github.com/valyala/fastjson/issues/new).
if such restriction is mentioned in [docs](https://github.com/wundergraph/astjson/issues/new).
* Build and run your program with [-race](https://golang.org/doc/articles/race_detector.html) flag.
Make sure the race detector detects zero races.
* If your program continue crashing after fixing issues mentioned above, [file a bug](https://github.com/valyala/fastjson/issues/new).
* If your program continue crashing after fixing issues mentioned above, [file a bug](https://github.com/wundergraph/astjson/issues/new).
10 changes: 5 additions & 5 deletions arena.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package fastjson
package astjson

import (
"strconv"
Expand All @@ -8,10 +8,10 @@ import (
//
// Typical Arena lifecycle:
//
// 1) Construct Values via the Arena and Value.Set* calls.
// 2) Marshal the constructed Values with Value.MarshalTo call.
// 3) Reset all the constructed Values at once by Arena.Reset call.
// 4) Go to 1 and re-use the Arena.
// 1. Construct Values via the Arena and Value.Set* calls.
// 2. Marshal the constructed Values with Value.MarshalTo call.
// 3. Reset all the constructed Values at once by Arena.Reset call.
// 4. Go to 1 and re-use the Arena.
//
// It is unsafe calling Arena methods from concurrent goroutines.
// Use per-goroutine Arenas or ArenaPool instead.
Expand Down
2 changes: 1 addition & 1 deletion arena_test.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package fastjson
package astjson

import (
"fmt"
Expand Down
2 changes: 1 addition & 1 deletion arena_timing_test.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package fastjson
package astjson

import (
"sync/atomic"
Expand Down
5 changes: 2 additions & 3 deletions doc.go
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
/*
Package fastjson provides fast JSON parsing.
Package astjson provides fast JSON parsing.
Arbitrary JSON may be parsed by fastjson without the need for creating structs
or for generating go code. Just parse JSON and get the required fields with
Get* functions.
*/
package fastjson
package astjson
3 changes: 2 additions & 1 deletion fuzz.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
//go:build gofuzz
// +build gofuzz

package fastjson
package astjson

func Fuzz(data []byte) int {
err := ValidateBytes(data)
Expand Down
4 changes: 2 additions & 2 deletions go.mod
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
module github.com/valyala/fastjson
module github.com/wundergraph/astjson

go 1.12
go 1.21
2 changes: 1 addition & 1 deletion handy.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package fastjson
package astjson

var handyPool ParserPool

Expand Down
21 changes: 11 additions & 10 deletions handy_example_test.go
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
package fastjson_test
package astjson_test

import (
"fmt"
"github.com/valyala/fastjson"

"github.com/wundergraph/astjson"
)

func ExampleGetString() {
data := []byte(`{"foo":{"bar":[123,"baz"]}}`)

s := fastjson.GetString(data, "foo", "bar", "1")
s := astjson.GetString(data, "foo", "bar", "1")
fmt.Printf("data.foo.bar[1] = %s", s)

// Output:
Expand All @@ -18,10 +19,10 @@ func ExampleGetString() {
func ExampleGetInt() {
data := []byte(`{"foo": [233,true, {"bar": [2343]} ]}`)

n1 := fastjson.GetInt(data, "foo", "0")
n1 := astjson.GetInt(data, "foo", "0")
fmt.Printf("data.foo[0] = %d\n", n1)

n2 := fastjson.GetInt(data, "foo", "2", "bar", "0")
n2 := astjson.GetInt(data, "foo", "2", "bar", "0")
fmt.Printf("data.foo[2].bar[0] = %d\n", n2)

// Output:
Expand All @@ -32,11 +33,11 @@ func ExampleGetInt() {
func ExampleExists() {
data := []byte(`{"foo": [1.23,{"bar":33,"baz":null}]}`)

fmt.Printf("exists(data.foo) = %v\n", fastjson.Exists(data, "foo"))
fmt.Printf("exists(data.foo[0]) = %v\n", fastjson.Exists(data, "foo", "0"))
fmt.Printf("exists(data.foo[1].baz) = %v\n", fastjson.Exists(data, "foo", "1", "baz"))
fmt.Printf("exists(data.foobar) = %v\n", fastjson.Exists(data, "foobar"))
fmt.Printf("exists(data.foo.bar) = %v\n", fastjson.Exists(data, "foo", "bar"))
fmt.Printf("exists(data.foo) = %v\n", astjson.Exists(data, "foo"))
fmt.Printf("exists(data.foo[0]) = %v\n", astjson.Exists(data, "foo", "0"))
fmt.Printf("exists(data.foo[1].baz) = %v\n", astjson.Exists(data, "foo", "1", "baz"))
fmt.Printf("exists(data.foobar) = %v\n", astjson.Exists(data, "foobar"))
fmt.Printf("exists(data.foo.bar) = %v\n", astjson.Exists(data, "foo", "bar"))

// Output:
// exists(data.foo) = true
Expand Down
2 changes: 1 addition & 1 deletion handy_test.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package fastjson
package astjson

import (
"fmt"
Expand Down
5 changes: 3 additions & 2 deletions parser.go
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
package fastjson
package astjson

import (
"fmt"
"github.com/valyala/fastjson/fastfloat"
"strconv"
"strings"
"unicode/utf16"

"github.com/wundergraph/astjson/fastfloat"
)

// Parser parses JSON.
Expand Down
21 changes: 11 additions & 10 deletions parser_example_test.go
Original file line number Diff line number Diff line change
@@ -1,14 +1,15 @@
package fastjson_test
package astjson_test

import (
"fmt"
"github.com/valyala/fastjson"
"log"
"strconv"

"github.com/wundergraph/astjson"
)

func ExampleParser_Parse() {
var p fastjson.Parser
var p astjson.Parser
v, err := p.Parse(`{"foo":"bar", "baz": 123}`)
if err != nil {
log.Fatalf("cannot parse json: %s", err)
Expand All @@ -21,7 +22,7 @@ func ExampleParser_Parse() {
}

func ExampleParser_Parse_reuse() {
var p fastjson.Parser
var p astjson.Parser

// p may be re-used for parsing multiple json strings.
// This improves parsing speed by reducing the number
Expand Down Expand Up @@ -61,7 +62,7 @@ func ExampleValue_MarshalTo() {
}
]
}`
var p fastjson.Parser
var p astjson.Parser
v, err := p.Parse(s)
if err != nil {
log.Fatalf("cannot parse json: %s", err)
Expand All @@ -82,7 +83,7 @@ func ExampleValue_MarshalTo() {

func ExampleValue_Get() {
s := `{"foo":[{"bar":{"baz":123,"x":"434"},"y":[]},[null, false]],"qwe":true}`
var p fastjson.Parser
var p astjson.Parser
v, err := p.Parse(s)
if err != nil {
log.Fatalf("cannot parse json: %s", err)
Expand Down Expand Up @@ -123,7 +124,7 @@ func ExampleValue_Type() {
"null": null
}`

var p fastjson.Parser
var p astjson.Parser
v, err := p.Parse(s)
if err != nil {
log.Fatalf("cannot parse json: %s", err)
Expand Down Expand Up @@ -154,7 +155,7 @@ func ExampleObject_Visit() {
"str": "foobar"
}`

var p fastjson.Parser
var p astjson.Parser
v, err := p.Parse(s)
if err != nil {
log.Fatalf("cannot parse json: %s", err)
Expand All @@ -164,7 +165,7 @@ func ExampleObject_Visit() {
log.Fatalf("cannot obtain object from json value: %s", err)
}

o.Visit(func(k []byte, v *fastjson.Value) {
o.Visit(func(k []byte, v *astjson.Value) {
switch string(k) {
case "obj":
fmt.Printf("object %s\n", v)
Expand All @@ -187,7 +188,7 @@ func ExampleValue_GetStringBytes() {
[123, "baz"]
]`

var p fastjson.Parser
var p astjson.Parser
v, err := p.Parse(s)
if err != nil {
log.Fatalf("cannot parse json: %s", err)
Expand Down
2 changes: 1 addition & 1 deletion parser_test.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package fastjson
package astjson

import (
"fmt"
Expand Down
2 changes: 1 addition & 1 deletion parser_timing_test.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package fastjson
package astjson

import (
"encoding/json"
Expand Down
2 changes: 1 addition & 1 deletion pool.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package fastjson
package astjson

import (
"sync"
Expand Down
2 changes: 1 addition & 1 deletion scanner.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
package fastjson
package astjson

import (
"errors"
Expand Down
Loading

0 comments on commit 14b02b3

Please sign in to comment.