wyrihaximus / react-stream-json
Incremental JSON encoder writing to a react/stream
Fund package maintenance!
WyriHaximus
Installs: 61 919
Dependents: 4
Suggesters: 0
Security: 0
Stars: 7
Watchers: 3
Forks: 2
Open Issues: 3
Requires
- php: ^8.1
- ext-json: *
- evenement/evenement: ^3.0
- react/promise: ^2.10
- react/stream: ^1.1.0
- reactivex/rxphp: ^2.0
- thecodingmachine/safe: ^1.3 || ^2
Requires (Dev)
- api-clients/rx: ^2.2
- react/promise-stream: ^1.5
- wyrihaximus/async-test-utilities: ^5.0.25 || ^6 || ^7
- wyrihaximus/ticking-promise: ^3
- dev-master
- 1.4.2
- 1.4.1
- 1.4.0
- 1.3.1
- 1.3.0
- 1.2.0
- 1.1.0
- 1.0.2
- 1.0.1
- 1.0.0
- dev-renovate/major-phpunit
- dev-dependabot/composer/composer/composer-2.7.0
- dev-renovate/react-promise-3.x
- dev-update-ci-workflow-to-latest-gen
- dev-dependabot/add-v2-config-file
- dev-dependabot/composer/reactivex/rxphp-2.0.8
- dev-json-stream-factory
- dev-add-observable-support
- dev-react-promise-stream-1.0-and-0.1
This package is auto-updated.
Last update: 2024-10-07 04:39:33 UTC
README
Installation
To install via Composer, use the command below, it will automatically detect the latest version and bind it with ^
.
composer require wyrihaximus/react-stream-json
Usage
The JsonStream
implements the ReadableStreamInterface
from react/stream
and behaves like the ThroughStream
, the moment you write*
to it, it will emit data.
The following example has a fixed number of items in the JSON and can be written to end
with out needed a write*
call.
$stream = new ThroughStream(); $anotherStream = new ThroughStream(); $jsonStream = new JsonStream(); $jsonStream->end([ 'key' => 'value', 'promise' => resolve('value'), 'stream' => $stream, 'nested' => [ 'a' => 'b', 'c' => 'd', ], 'nested_promises' => [ resolve('first'), resolve('second'), ], 'nested_mixed' => [ 'first', resolve($anotherStream), resolve('third'), ], ]); $stream->end('stream contents'); $anotherStream->end('second');
Stream contents will be:
{"key":"value","promise":"value","stream":"stream contents","nested":{"a":"b","c":"d"},"nested_promises":["first","second"],"nested_mixed":["first","second","third"]}
Methods
All the following methods try to resolve $value
, when it encounters a promise it will wait for the promise
to resolve, and when it encounters a stream it will forward the stream's contents to it's own listeners.
Promises can resolve to a stream but not vise versa. Any other parameters will be run though json_encode
,
except for arrays, those will be searched through for promises and streams.
write
write(string $key, $value)
accepts a key and a value as argument. Writing a new key and value pair to the stream.
writeValue
write($value)
accepts only a value as argument. Writing the value pair to the stream.
writeArray
writeArray(array $values)
will iterate over the items in the array and call write
or writeValue
depending on
the type of the key.
writeObservable
writeObservable(ObservableInterface $values)
will subscribe to the observable and call writeValue
on each item
coming in.
end
end(array $values = [])
will call writeArray
when $values
contains something and then or otherwise
end the stream. At that point no new values are accepted and it continues to operate any outstanding promises or streams
have been resolve/completed.
Caveats
The stream doesn't know if you want to write an object or an array so it assumes an object.
It does try to detect when you haven't written anything yet and call writeArray
or end
with an array of items. You can force writing an array or object by calling JsonStream::createArray
or JsonStream::createObject
when creating an instance of JsonStream
. Writing object items
to a stream set up as array or vise versa will result in malformed JSON
. In short you MUST
know what kind of JSON
you will be writing.
When using write
the key parameter isn't checked duplicates resulting in writing it
out again to the stream. Bear in mind that while PHP
considers this perfectly valid JSON
, the
JSON
spec doesn't specify a behavior for this. So your
milage might vary, as described in section 4 of
RFC7159, in PHP
's case it will only use the value from the last occurrence.
Factories
This package ships with a factory containing factory methods for arrays JsonStreamFactory::createFromArray
and
observables JsonStreamFactory::createFromObservable
. Both will create a few stream, pause it, write the
array/observable to it, and end it.
Contributing
Please see CONTRIBUTING for details.
License
Copyright 2019 Cees-Jan Kiewiet
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.