feat: impl localstroage and filystem module

other modules still WIP

Co-authored-by: MasterMarcoHD <MasterMarcoHD@users.noreply.github.com>

Author: mcquenji

README.md

@@ -1,36 +1,114 @@
 # Grumpy IO
 
-Full IO mapping for Grumpy applications, providing a unified API for file system access, networking, and local storage across all platforms.
-
-## Modules
-
-- [ ] File System Module
-  - [ ] File System CRUD operations
-  - [ ] File Picker
-  - [ ] Filesystem Watcher
-  - [ ] File Metadata Extraction
-- [ ] Networking Module
-  - [x] Network Requests
-  - [ ] Typed Response parsing via datasources
-  - [ ] WebSocket Support
-  - [ ] Network Connectivity Monitoring
-  - [ ] Data Streaming
-  - [ ] Downloading, with progress tracking
-  - [ ] Uploading, with progress tracking
-- [ ] Local Storage
-  - [ ] App Directories
-    - [ ] Temporary Directory/temp files
-    - [ ] Persistent Directory
-    - [ ] Cache Directory
-  - [ ] Cookies
-- [ ] Process management (desktop only, noop for web and mobile)
-  - [ ] Spawn processes
-  - [ ] Inter-process communication (IPC)
-  - [ ] Process monitoring and control
-  - [ ] Force single app instance
-  - [ ] Run shell commands
-  - [ ] Command line argument parsing (via config)
-- [ ] System information
-  - [ ] OS details
-  - [ ] Hardware specifications
-  - [ ] Environment variables
+`grumpy_io` provides cross-platform IO services and typed datasource adapters for Grumpy apps.
+
+It covers:
+- raw networking
+- raw filesystem
+- persistent local storage
+- typed datasource wrappers in each owning module
+- optional Grumpy cache/persistence compatibility adapters
+
+## Design Goals
+
+- Keep public IO contracts backend-agnostic.
+- Return typed `IoResult<T>` instead of leaking backend exceptions.
+- Keep typed datasources close to their owning module.
+- Use compile-time platform selection for platform-specific services.
+
+## Module Layout
+
+### Networking Module
+
+Exports:
+- `NetworkService`
+- `FileTransferService`
+- `TypedNetworkDatasource`
+
+Default implementations:
+- `DioNetworkService`
+- `DefaultFileTransferService`
+- `DefaultTypedNetworkDatasource`
+
+### File System Module
+
+Exports:
+- `FileSystemService`
+- `TypedFileSystemDatasource`
+- `IoPath`, `FsMetadata`, `FsEntityType`
+
+Default implementations:
+- `DefaultFileSystemService` (platform-selected)
+- `DefaultTypedFileSystemDatasource`
+
+### Local Storage Module
+
+Exports:
+- `LocalStorageService`
+- `TypedLocalStorageDatasource`
+- `LocalStorageKey`, `LocalStorageValue`
+
+Default implementations:
+- `DefaultLocalStorageService` (platform-selected)
+- `DefaultTypedLocalStorageDatasource`
+
+Persistence behavior:
+- Native (`io`): persisted via `FileSystemService` in a JSON file.
+- Web: persisted in browser `localStorage` with cookie fallback.
+
+## Typed Datasources
+
+Typed datasources are intentionally colocated with their modules:
+- networking typed datasource lives in networking module
+- filesystem typed datasource lives in filesystem module
+- local-storage typed datasource lives in local-storage module
+
+Shared typed datasource concerns are in `shared_module`.
+
+## Platform-Specific Service Convention
+
+For services with platform-specific implementations:
+- platform files live under `<module>/infra/services/<service>/...`
+- an entrypoint file performs conditional export
+- concrete platform implementations expose the same symbols
+
+Example pattern:
+
+```dart
+export 'service_stub.dart'
+    if (dart.library.io) 'service_io.dart'
+    if (dart.library.js_interop) 'service_web.dart';
+```
+
+## Error Model
+
+All public IO surfaces use:
+- `IoResult<T>`
+- `IoOk<T>`
+- `IoErr<T>`
+- `IoFailure` with `IoFailureCode`
+
+This keeps consumers on one stable error contract across backends/platforms.
+
+## Grumpy Compatibility Layer
+
+`grumpy_compat` provides optional adapters for:
+- memory cache layer
+- persistent cache layer
+- cache pipeline
+- repo snapshot persistence
+- root module mixin wiring
+
+## Public Exports
+
+Package root exports:
+- `core`
+- `networking_module`
+- `file_system_module`
+- `local_storage_module`
+- `grumpy_compat`
+- `grumpy_io_module`
+
+## Status
+
+Current focus is V1 core IO and persistence surfaces. Process-management and system-information features remain out of scope for V1.

analysis_options.yaml

@@ -21,8 +21,12 @@ plugins:
       must_call_in_constructor: true
       abstract_classes_should_set_log_group: true
       concrete_classes_should_set_log_tag: true
-      base_class: true
-      domain_factory_from_di: true
+      base_class:
+        enabled: true
+        ignorable: true
+      domain_factory_from_di:
+        enabled: true
+        ignorable: true
       prefer_domain_di_factory: true
       lifecycle_mixin_requires_singleton: true
 

lib/grumpy_io.dart

@@ -1,2 +1,6 @@
+export 'src/core/core.dart';
 export 'src/file_system_module/file_system_module.dart';
+export 'src/grumpy_compat/grumpy_compat.dart';
+export 'src/grumpy_io_module/grumpy_io_module.dart';
+export 'src/local_storage_module/local_storage_module.dart';
 export 'src/networking_module/networking_module.dart';

lib/src/core/core.dart

@@ -0,0 +1,3 @@
+export 'domain/models/models.dart';
+export 'domain/datasources/datasources.dart';
+export 'domain/codecs/codecs.dart';

lib/src/core/domain/codecs/codecs.dart

@@ -0,0 +1,2 @@
+export 'json_utf8_codec.dart';
+export 'string_utf8_codec.dart';

lib/src/core/domain/codecs/json_utf8_codec.dart

@@ -0,0 +1,55 @@
+import 'dart:convert';
+
+import 'package:grumpy/grumpy.dart';
+
+import '../models/io_result.dart';
+
+/// Convenience base for JSON-object codecs serialized as UTF-8 bytes.
+abstract class JsonUtf8Codec<T> implements SerializationCodec<T, Bytes> {
+  /// Creates a JSON codec.
+  const JsonUtf8Codec();
+
+  /// Converts [value] into a JSON object.
+  JsonMap toJson(T value);
+
+  /// Converts a JSON object into the target type.
+  T fromJson(JsonMap json);
+
+  @override
+  Bytes encode(T value) {
+    return Bytes.fromList(utf8.encode(jsonEncode(toJson(value))));
+  }
+
+  @override
+  T decode(Bytes payload) {
+    final dynamic decoded = jsonDecode(utf8.decode(payload));
+    if (decoded is! Map) {
+      throw const FormatException('Expected JSON object payload.');
+    }
+    return fromJson(Map<String, Object?>.from(decoded));
+  }
+
+  /// Creates a JSON codec from [toJson] and [fromJson] functions.
+  const factory JsonUtf8Codec.from({
+    required JsonMap Function(T value) toJson,
+    required T Function(JsonMap json) fromJson,
+  }) = _JsonUtf8CodecImpl;
+}
+
+class _JsonUtf8CodecImpl<T> extends JsonUtf8Codec<T> {
+  const _JsonUtf8CodecImpl({
+    required JsonMap Function(T value) toJson,
+    required T Function(JsonMap json) fromJson,
+  }) : _toJson = toJson,
+       _fromJson = fromJson;
+
+  final JsonMap Function(T value) _toJson;
+
+  final T Function(JsonMap json) _fromJson;
+
+  @override
+  T fromJson(JsonMap json) => _fromJson(json);
+
+  @override
+  JsonMap toJson(T value) => _toJson(value);
+}

lib/src/core/domain/codecs/string_utf8_codec.dart

@@ -0,0 +1,17 @@
+import 'dart:convert';
+
+import 'package:grumpy/grumpy.dart';
+
+import '../models/io_result.dart';
+
+/// UTF-8 codec for plain text payloads.
+class StringUtf8Codec implements SerializationCodec<String, Bytes> {
+  /// Creates a string codec.
+  const StringUtf8Codec();
+
+  @override
+  Bytes encode(String value) => Bytes.fromList(utf8.encode(value));
+
+  @override
+  String decode(Bytes payload) => utf8.decode(payload);
+}

lib/src/core/domain/datasources/datasources.dart

@@ -0,0 +1 @@
+export 'typed_datasource.dart';

lib/src/core/domain/datasources/typed_datasource.dart

@@ -0,0 +1,15 @@
+// This is a base type for typed datasource abstractions, and is not to be instantiated directly.
+// ignore_for_file: domain_factory_from_di_missing_factory
+
+import 'package:grumpy/grumpy.dart';
+
+/// Base type for module-local typed datasource abstractions.
+abstract class TypedDatasource extends Datasource {
+  /// Creates a typed datasource.
+  const TypedDatasource.internal() : super();
+
+  @override
+  bool get singelton => true;
+  @override
+  String get group => '${super.group}.TypedDatasource';
+}

lib/src/core/domain/models/io_result.dart

@@ -0,0 +1,125 @@
+import 'dart:async';
+import 'dart:typed_data';
+
+/// Canonical byte payload type used across network/storage/filesystem services.
+typedef Bytes = Uint8List;
+
+/// Stable, backend-agnostic failure categories used by `grumpy_io`.
+enum IoFailureCode {
+  /// This operation is not supported by the current platform or configuration.
+  unsupported,
+
+  /// The requested resource was not found.
+  notFound,
+
+  /// The requested resource already exists.
+  alreadyExists,
+
+  /// Insufficient permissions to perform this operation.
+  permissionDenied,
+
+  /// The operation took too long to complete.
+  timeout,
+
+  /// An error in the underlying network stack (e.g. DNS failure, connection reset, etc.).
+  networkError,
+
+  /// The data is malformed or does not conform to expected format/schema.
+  invalidData,
+
+  /// The operation was cancelled by the caller before completion.
+  cancelled,
+
+  /// An unexpected error occurred (e.g. unhandled exception, etc.).
+  unknown,
+}
+
+/// A typed IO failure envelope.
+class IoFailure {
+  /// Creates an IO failure.
+  const IoFailure({
+    required this.code,
+    required this.message,
+    this.cause,
+    this.details = const <String, Object?>{},
+    this.stackTrace,
+  });
+
+  /// Failure category.
+  final IoFailureCode code;
+
+  /// Human-readable failure summary.
+  final String message;
+
+  /// Optional original cause.
+  final Object? cause;
+
+  /// Optional structured context for callers/logging.
+  final Map<String, Object?> details;
+
+  /// Optional stack trace when failure was captured.
+  final StackTrace? stackTrace;
+
+  @override
+  String toString() => 'IoFailure(code: $code, message: $message)';
+}
+
+/// Functional-style result for IO operations.
+sealed class IoResult<T> {
+  /// Creates a result value.
+  const IoResult();
+
+  /// Returns `true` when this result is [IoOk].
+  bool get isOk => this is IoOk<T>;
+
+  /// Returns `true` when this result is [IoErr].
+  bool get isErr => this is IoErr<T>;
+
+  /// Returns [IoOk.value] or `null`.
+  T? get valueOrNull => switch (this) {
+    IoOk<T>(value: final value) => value,
+    IoErr<T>() => null,
+  };
+
+  /// Returns [IoErr.failure] or `null`.
+  IoFailure? get failureOrNull => switch (this) {
+    IoOk<T>() => null,
+    IoErr<T>(failure: final failure) => failure,
+  };
+}
+
+/// Successful IO result.
+final class IoOk<T> extends IoResult<T> {
+  /// Creates a successful result carrying [value].
+  const IoOk(this.value);
+
+  /// Successful payload.
+  final T value;
+}
+
+/// Failed IO result.
+final class IoErr<T> extends IoResult<T> {
+  /// Creates a failed result carrying [failure].
+  const IoErr(this.failure);
+
+  /// Failure payload.
+  final IoFailure failure;
+
+  /// Creates a failed result for an unsupported operation.
+  const factory IoErr.unsupported([String? operation]) = _UnsupportedIoErr;
+}
+
+final class _UnsupportedIoErr<T> extends IoErr<T> {
+  final String? operation;
+
+  const _UnsupportedIoErr([this.operation])
+    : super(const IoFailure(code: IoFailureCode.unsupported, message: ''));
+
+  @override
+  IoFailure get failure => IoFailure(
+    code: IoFailureCode.unsupported,
+    message: operation == null
+        ? 'This operation is not supported by the current platform or configuration.'
+        : 'The operation "$operation" is not supported by the current platform or configuration.',
+  );
+}